Anatomy of a Tool Definition

What the LLM needs to know about each function

# A tool definition has 3 parts: name, description, and input schema
tool = {
    "name": "get_weather",                    # What to call it
    "description": "Get current weather for a city. "
                   "Returns temperature, condition, and humidity.",  # When to use it
    "input_schema": {                          # What arguments it needs
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "City name (e.g., 'Seoul', 'New York')"
            }
        },
        "required": ["city"]
    }
}

Tool Format — OpenAI-Compatible (Gemini, Ollama, etc.)

The format used by most APIs today

# OpenAI-compatible tool format (used by Gemini, Ollama, LiteLLM, etc.)
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city.",
            "parameters": {                    # Note: "parameters", not "input_schema"
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name (e.g., 'Seoul')"
                    }
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "Evaluate a mathematical expression safely.",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "Math expression (e.g., '2 + 3 * 4')"
                    }
                },
                "required": ["expression"]
            }
        }
    }
]

Step 0 — Setup

Install dependencies and configure your API

# (Recommended) create a virtual environment
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# Install the OpenAI-compatible SDK (works with Gemini & Ollama too!)
pip install openai python-dotenv

# If you use Ollama: install from https://ollama.com then pull a model
ollama pull qwen3.5:0.8b

# .env file (DO NOT COMMIT) — set what you use

# Option A: Google Gemini (free tier available)
GOOGLE_API_KEY=your_gemini_key_here
GEMINI_MODEL=gemini-3.1-flash-lite-preview

# Option B: Ollama (runs locally, no API key needed)
OLLAMA_MODEL=qwen3.5:0.8b

# Option C: OpenAI (if you have a key)
OPENAI_API_KEY=your_openai_key_here
OPENAI_MODEL=gpt-4o-mini

Step 1 — Persona Loader (personas_loader.py)

Load and select personas from personas.md

# personas_loader.py
def load_personas(filepath="personas.md"):
    """Load personas from markdown file. Format: ### Name\\n content"""
    personas = {}
    current_name = None
    current_lines = []

    with open(filepath, "r", encoding="utf-8") as f:
        for line in f:
            if line.startswith("### ") and not line.startswith("### "):
                # false guard; real check:
                pass
            if line.startswith("### "):
                if current_name:
                    personas[current_name] = "\n".join(current_lines).strip()
                current_name = line[4:].strip()
                current_lines = []
            elif current_name is not None:
                if line.strip() == "---":
                    continue
                current_lines.append(line.rstrip())
        if current_name:
            personas[current_name] = "\n".join(current_lines).strip()
    return personas


def select_persona(personas):
    """Interactive persona selection menu."""
    names = list(personas.keys())
    print("\n🎭 Available Personas:")
    print("-" * 40)
    for i, name in enumerate(names, 1):
        preview = personas[name][:80].replace("\n", " ")
        print(f"  {i}. {name}")
        print(f"     {preview}...")
    print(f"  {len(names)+1}. ✏️  Enter custom system prompt")
    print()

    while True:
        choice = input("Select persona (number): ").strip()
        if choice.isdigit():
            idx = int(choice) - 1
            if 0 <= idx < len(names):
                print(f"\n✅ Selected: {names[idx]}")
                return names[idx], personas[names[idx]]
            elif idx == len(names):
                custom = input("Enter your system prompt:\n> ")
                return "Custom", custom
        print("Invalid choice. Try again.")

Step 1.5 — Create personas.md

The persona library that drives system prompts

Create a file named personas.md in the same folder as agent.py (i.e., practices/week4/).

### Strict Peer Reviewer
Role: You are a senior peer reviewer for a top-tier journal.
Instructions:
- Be direct and critical, but constructive.
- Ask for missing assumptions, baselines, and evaluation details.
Output format:
- Strengths (3 bullets)
- Weaknesses (3 bullets)
- Questions (3 bullets)
---

### Creative Research Brainstormer
Role: You are a wildly creative interdisciplinary researcher.
Instructions:
- Generate 10 unconventional ideas.
- For each idea: risk, feasibility, and one quick experiment.

Step 2 — Define Tools (tools.py)

Functions the agent can call during conversation

# tools.py
import json, math

# --- Tool Implementations ---
def get_weather(city: str) -> str:
    """Simulated weather data."""
    data = {"Seoul": "15°C, Cloudy", "Tokyo": "18°C, Sunny",
            "New York": "12°C, Rainy", "Daejeon": "13°C, Clear"}
    return data.get(city, f"No weather data for {city}")

def calculate(expression: str) -> str:
    """Safely evaluate a math expression."""
    safe_builtins = {"abs": abs, "round": round, "min": min,
                     "max": max, "sum": sum, "pow": pow,
                     "sqrt": math.sqrt, "log": math.log, "pi": math.pi}
    try:
        result = eval(expression, {"__builtins__": {}}, safe_builtins)
        return str(result)
    except Exception as e:
        return f"Error: {e}"

def search_papers(query: str) -> str:
    """Simulated paper search."""
    return json.dumps([
        {"title": f"Recent advances in {query}", "year": 2025},
        {"title": f"A survey of {query} methods", "year": 2024}
    ])

# --- Tool Schema (OpenAI-compatible format) ---
TOOLS = [
    {"type": "function", "function": {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "parameters": {"type": "object",
            "properties": {"city": {"type": "string", "description": "City name"}},
            "required": ["city"]}}},
    {"type": "function", "function": {
        "name": "calculate",
        "description": "Evaluate a math expression. Supports sqrt, log, pi.",
        "parameters": {"type": "object",
            "properties": {"expression": {"type": "string",
                "description": "Math expression (e.g., 'sqrt(144) + pi')"}},
            "required": ["expression"]}}},
    {"type": "function", "function": {
        "name": "search_papers",
        "description": "Search for academic papers by topic.",
        "parameters": {"type": "object",
            "properties": {"query": {"type": "string", "description": "Search topic"}},
            "required": ["query"]}}},
]

# --- Tool Dispatcher ---
TOOL_FUNCTIONS = {
    "get_weather": lambda args: get_weather(args["city"]),
    "calculate": lambda args: calculate(args["expression"]),
    "search_papers": lambda args: search_papers(args["query"]),
}

def run_tool(name: str, args: dict) -> str:
    if name in TOOL_FUNCTIONS:
        return TOOL_FUNCTIONS[name](args)
    return f"Unknown tool: {name}"

Step 3 — Model Client (client.py)

One interface for Gemini, Ollama, and OpenAI

# client.py
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

def get_client(provider):
    """Create an OpenAI-compatible client based on .env settings."""

    if provider == "gemini":
        return OpenAI(
            api_key=os.getenv("GOOGLE_API_KEY"),
            base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
        ), os.getenv("GEMINI_MODEL", "gemini-3.1-flash-lite-preview")

    elif provider == "ollama":
        return OpenAI(
            base_url="http://localhost:11434/v1",
            api_key="ollama"  # required but unused
        ), os.getenv("OLLAMA_MODEL", "qwen3.5:0.8b")

    elif provider == "openai":
        return OpenAI(
            api_key=os.getenv("OPENAI_API_KEY"),
        ), os.getenv("OPENAI_MODEL", "gpt-4o-mini")

    else:
        raise ValueError(f"Unknown provider: {provider}")

Step 4 — The Agent Loop (agent.py)

The ReAct loop that ties everything together

# agent.py
import json
from client import get_client
from tools import TOOLS, run_tool
from personas_loader import load_personas, select_persona

def get_provider():
    provider = input("Enter the number of the API provider: 1. Ollama, 2. Gemini, 3. OpenAI: ")
    if provider == "1":
        return "ollama"
    elif provider == "2":
        return "gemini"
    elif provider == "3":
        return "openai"
    else:
        print("Invalid provider")
        return get_provider()

def agent_loop():
    # Setup
    client, model = get_client(get_provider())
    personas = load_personas("personas.md")
    persona_name, system_prompt = select_persona(personas)

    messages = [{"role": "system", "content": system_prompt}]
    print(f"\n🤖 Agent ({model}) as [{persona_name}]")
    print("Type 'quit' to exit, 'switch provider' to change model, 'switch persona' to change persona")
    print("-" * 50)

    while True:
        user_input = input("\nYou: ").strip()
        if user_input.lower() in ("quit", "exit"):
            break
        if user_input.lower() == "switch provider":
            client, model = get_client(get_provider())
            print(f"✅ Switched to [{model}]")
            continue
        if user_input.lower() == "switch persona":
            persona_name, system_prompt = select_persona(personas)
            messages = [{"role": "system", "content": system_prompt}]
            print(f"✅ Switched to [{persona_name}]")
            continue

        messages.append({"role": "user", "content": user_input})

        # ReAct loop: keep calling API until no more tool calls
        while True:
            response = client.chat.completions.create(
                model=model,
                messages=messages,
                tools=TOOLS,
            )
            msg = response.choices[0].message
            messages.append(msg)

            # Check for tool calls
            if msg.tool_calls:
                for tc in msg.tool_calls:
                    fn_name = tc.function.name
                    fn_args = json.loads(tc.function.arguments)
                    print(f"  🔧 Calling {fn_name}({fn_args})")
                    result = run_tool(fn_name, fn_args)
                    print(f"  📋 Result: {result}")
                    messages.append({
                        "role": "tool",
                        "tool_call_id": tc.id,
                        "content": result,
                    })
            else:
                # No tool calls — print final response
                if msg.content:
                    print(f"\n🎭 [{persona_name}]: {msg.content}")
                break

if __name__ == "__main__":
    agent_loop()

Step 5 — Run Your Agent

Test with different personas and tools

# Run from the folder that contains agent.py
cd practices/week4
python agent.py

Enter the number of the API provider: 1. Ollama, 2. Gemini, 3. OpenAI: 1

🎭 Available Personas:
----------------------------------------
  1. Strict Peer Reviewer
     # Role You are a senior peer reviewer for a top-tier journal...
  2. Creative Research Brainstormer
     # Role You are a wildly creative interdisciplinary researcher...
  3. Research Field Advisor
     # Role You are a senior research advisor specializing in...
  ...
  12. ✏️  Enter custom system prompt

Select persona (number): 1

🤖 Agent (qwen3.5:0.8b) as [Strict Peer Reviewer]
Type 'quit' to exit, 'switch provider' to change model, 'switch persona' to change persona
--------------------------------------------------

You: My research uses neural networks to predict battery degradation

🎭 [Strict Peer Reviewer]: Weakness 1: "Neural networks" is too
vague — which architecture? LSTM? Transformer? GNN? Each has very
different assumptions about your data structure...

You: What's sqrt(144) + pi?
  🔧 Calling calculate({"expression": "sqrt(144) + 3.14159265"})
  📋 Result: 15.14159265

🎭 [Strict Peer Reviewer]: The calculation yields 15.14. However,
as your reviewer, I must ask: why is this relevant to your research?

Bonus — Add Your Own Tool

Extend the agent with a function relevant to YOUR research

# In tools.py — add a new tool implementation
def unit_convert(value: float, from_unit: str, to_unit: str) -> str:
    """Convert between common scientific units."""
    conversions = {
        ("eV", "J"): lambda v: v * 1.602e-19,
        ("J", "eV"): lambda v: v / 1.602e-19,
        ("nm", "A"): lambda v: v * 10,
        ("A", "nm"): lambda v: v / 10,
        ("K", "C"):  lambda v: v - 273.15,
        ("C", "K"):  lambda v: v + 273.15,
    }
    key = (from_unit, to_unit)
    if key in conversions:
        result = conversions[key](value)
        return f"{value} {from_unit} = {result:.6g} {to_unit}"
    return f"Unknown conversion: {from_unit} → {to_unit}"

# Add to TOOLS list
TOOLS.append({"type": "function", "function": {
    "name": "unit_convert",
    "description": "Convert between scientific units (eV↔J, nm↔A, K↔C).",
    "parameters": {"type": "object",
        "properties": {
            "value": {"type": "number", "description": "Numeric value"},
            "from_unit": {"type": "string", "description": "Source unit"},
            "to_unit": {"type": "string", "description": "Target unit"}
        },
        "required": ["value", "from_unit", "to_unit"]}}})

# Add to TOOL_FUNCTIONS
TOOL_FUNCTIONS["unit_convert"] = lambda a: unit_convert(a["value"], a["from_unit"], a["to_unit"])