Tools turn talk into action.

What a tool is.

A tool is a function the model can ask you to run. You tell the model what tools exist. The model decides when to call one. You execute it. The model uses the result.

The model never runs code directly. It returns a structured request — “please run get_weather with city='Phoenix'” — and waits. Your code runs the function and sends the answer back. The model then incorporates the result into its response.

This loop is the whole game. Once you see it, every agent in the world is the same diagram, just with more tools and more turns.

Declaring a tool.

A tool is described by JSON Schema. Name, description, parameters. The description matters — the model decides whether to call the tool by reading it.

From the last unit: You know what a tool is. Now you need to tell Claude about yours. The shape is JSON Schema; the leverage is the description.

Copytools = [
    {
        "name": "get_weather",
        "description": (
            "Get the current weather in a given city. "
            "Use this when the user asks about temperature, "
            "rain, sun, wind, or what to wear today."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name, e.g. Phoenix or San Diego",
                },
                "units": {
                    "type": "string",
                    "enum": ["fahrenheit", "celsius"],
                    "default": "fahrenheit",
                },
            },
            "required": ["city"],
        },
    }
]

Why the description is the most important field

The model doesn’t see your function code. It sees the name and the description. A good description tells the model not just what the tool does but when to reach for it. Treat it like a job description: specific about the cases, vague about the implementation.

The full tool-use loop.

Save this as tool_use_demo.py in the same agents/ folder you set up on Day 1. It declares two tools, calls Claude, and runs the loop until the model is done.

From the last unit: You have one tool declared. Now run the full loop end to end — the shape every agent in the world uses underneath.

The pattern works for any tool — reading a file, hitting an API, querying a database, running a shell command. Once you write the loop once, every agent is the same shape underneath.

Copy# tool_use_demo.py — full minimal loop
import json, datetime
from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-sonnet-4-6"

# 1. Declare the tools
tools = [
    {"name": "get_current_time",
     "description": "Return the current local date and time.",
     "input_schema": {"type": "object", "properties": {}}},
    {"name": "read_file",
     "description": "Read a UTF-8 text file from disk.",
     "input_schema": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"]}},
]

# 2. Implement the tools
def get_current_time():
    return datetime.datetime.now().isoformat(timespec="seconds")

def read_file(path):
    with open(path, "r", encoding="utf-8") as f:
        return f.read()[:8000]

TOOL_FNS = {
    "get_current_time": lambda **_: get_current_time(),
    "read_file":        lambda **a: read_file(a["path"]),
}

# 3. The loop
def run(user_prompt):
    messages = [{"role": "user", "content": user_prompt}]
    while True:
        resp = client.messages.create(
            model=MODEL, max_tokens=1024,
            tools=tools, messages=messages)
        messages.append({"role": "assistant", "content": resp.content})
        if resp.stop_reason != "tool_use":
            for b in resp.content:
                if b.type == "text": print(b.text)
            return
        tool_results = []
        for b in resp.content:
            if b.type != "tool_use": continue
            print(f"[tool] {b.name}({json.dumps(b.input)})")
            try: out = TOOL_FNS[b.name](**b.input)
            except Exception as e: out = f"ERROR: {e}"
            tool_results.append({"type": "tool_result",
                                 "tool_use_id": b.id, "content": str(out)})
        messages.append({"role": "user", "content": tool_results})

if __name__ == "__main__":
    run("What time is it? Then read ./demo.txt and summarize the file in three bullets.")

Run it

The prompt asks the model to read ./demo.txt, so create that file first — one line is enough. Then run the loop from inside the agents/ folder where you saved the script.

Copy# from the same agents/ folder you saved Day 1’s code into
cd agents
echo "Pradhya Day 03 demo: this line gets read by the tool-use loop." > demo.txt
python tool_use_demo.py

Example run

The two [tool] lines come from the print(...) in the loop — one per tool call — and everything after them is the model’s final answer:

Copy$ python tool_use_demo.py
[tool] get_current_time({})
[tool] read_file({"path": "./demo.txt"})
It’s 2026-06-10T09:14:22 right now. Here’s demo.txt in three bullets:
- It’s a placeholder file that gives the tool-use loop something real to read.
- It names the two tools the demo declares: get_current_time and read_file.
- It walks through the loop: the model requests a tool, your harness runs it,
  the model reads the result and writes this answer.

Your timestamp and exact wording will differ — the two tool calls and the file-grounded summary will not. You just built an agent.

Structured outputs.

Sometimes you don’t want the model to talk. You want a JSON object you can pass straight to another system.

From the last unit: Tool use returns a result the model reads. Sometimes you want the result to BE the answer — structured, typed, ready to pass to other code. Same mechanism, different intent.

The trick: define a tool that the model is forced to call. Its “input” becomes your structured output. This is the closest thing to a typed return value the model offers. The fragment below is complete — save it as structured_demo.py in your agents/ folder and run it.

Copy# structured_demo.py — force the model to fill a form
import json
from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-sonnet-4-6"

meeting_notes = """
Call with Dana Okafor (procurement lead, Northwind).
Still open: the SOC2 letter they asked for last week, and pricing for the 50-seat tier.
Dana wants a revised quote before their board meeting on Friday.
She mentioned the security review is the only blocker left on their side.
Budget is already approved on their end; legal sign-off is the long pole.
Next step on us: send the SOC2 letter and the revised 50-seat quote by Wednesday.
"""

tools = [{
    "name": "extract_meeting_brief",
    "description": "Return a structured one-page meeting brief.",
    "input_schema": {
        "type": "object",
        "properties": {
            "who":            {"type": "string"},
            "open_threads":   {"type": "array", "items": {"type": "string"}},
            "talking_points": {"type": "array", "items": {"type": "string"}, "minItems": 3, "maxItems": 3},
            "the_ask":        {"type": "string"},
        },
        "required": ["who", "open_threads", "talking_points", "the_ask"],
    },
}]

resp = client.messages.create(
    model=MODEL,
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "extract_meeting_brief"},
    messages=[{"role": "user", "content": meeting_notes}],
)
brief = resp.content[0].input   # already a typed Python dict
print(json.dumps(brief, indent=2))

Because tool_choice forces the call, you skip the loop entirely — one request, one typed dict back. This pattern is the foundation for the meeting-prep agent and the SEO content-brief workflow — anywhere you need a model to fill in a form rather than write prose.

The agentic discipline.

A tool-using model is a model with hands. Hands break things. Three rules separate a useful agent from an expensive mistake.

From the last unit: Tool use turns a model into an agent. An agent with hands can break things. Three rules separate a useful agent from an expensive mistake.

1. Scope it. Be explicit about which folder, which app, which account. An agent that can read your whole disk is an agent that will read your whole disk.
2. Preview before commit. Ask for the plan, approve it, then run. The cost of one extra round-trip is nothing compared to one wrong action.
3. Reversibility first. Drafts before sends. Copies before moves. Read-only before read-write. Build the agent so the worst thing it can do today is print something dumb.

Scope rule #1, in code

Your read_file from §03.03 reads any path the model names — including ~/.ssh/config. Rule #1 (scope it) is three lines: resolve the path and refuse anything outside the current folder. Swap your read_file for this version.

Copyimport pathlib

ALLOWED_ROOT = pathlib.Path.cwd().resolve()   # only this folder

def read_file(path):
    p = pathlib.Path(path).expanduser().resolve()
    if not str(p).startswith(str(ALLOWED_ROOT)):   # <-- the path-restriction line
        return f"ERROR: blocked — {p} is outside {ALLOWED_ROOT}"
    return p.read_text(encoding="utf-8", errors="replace")[:8000]