Build an Agent With Tools

What an agent actually is intermediate

The word "agent" has been stretched to mean almost nothing, so let's start with a moment that made it click for me. The first time I watched a model "use a tool," I expected magic — some special channel where the model reached out and touched the world. What actually happened was almost disappointing: the model sent back a little chunk of JSON that said "I'd like to call get_weather with city=Tokyo," and then it stopped and waited. My own code read that JSON, ran an ordinary Python function, and typed the answer back into the conversation like another message. That was it. The "agent" was a for loop I wrote, and the model was a very good suggestion engine sitting inside it. Once you see that the model never actually does anything — it only ever asks — the whole topic stops being mysterious and starts being engineering.

Here's the analogy that keeps you honest. Think of the model as a brilliant consultant on the phone who can't leave the room. They can reason, plan, and tell you exactly what to do next — "call this number, look up that record, delete that file" — but they have no hands. You are the hands. Every real action happens because your code chose to carry out the consultant's request. That framing matters because it tells you precisely where safety, validation, and control live: not in the model, but in the loop around it. The model proposes; your code disposes.

So, stripping away the hype: an agent is a while loop around the same API call you already know. The only new idea is tools — functions you describe to the model. When the model wants to use one, it doesn't run it (it can't); it asks you to by returning a tool_use block. Your code runs the function and feeds the result back. Repeat until the model is done. That cycle — think, act, observe — is the entire definition: the model thinks about what it needs, asks to act via a tool, and you feed back what it should observe, then it thinks again with that new information in hand.

The mistake almost everyone makes first is reaching for an agent when a plain workflow would do. If the steps are known in advance — retrieve, then summarize, then format — you don't need a model deciding the order at runtime; you need a script, and a script is cheaper, faster, and far more predictable. An agent earns its keep only when the path is genuinely unknown: when the next step depends on what the last step returned, when the model must choose among tools, when the task can't be flowcharted ahead of time. The callout below is the four-question filter to apply before you write a single line — reach for it every time, because "should this be an agent?" is a design decision, not a default.

The agentic loop, visualized intermediate

If you remember one picture from this whole chapter, make it this one. Every agent framework you'll ever meet — LangChain, the Claude Agent SDK, some 2,000-line orchestration engine at work — is, underneath all the abstraction, the little diagram below. People assume there must be more to it, and there isn't. When an agent misbehaves in production, the debugging always comes back to "which box are we in, and why did the arrow go the wrong way?" Learn the loop by hand here and you'll be able to read any framework's source without flinching.

The everyday analogy is a conversation with a capable assistant who keeps checking back in. You give them a goal. They either hand you the finished answer ("here's your report — done") or they come back with a question that requires you to go do something ("what's in that file?"). If it's a question, you go get the answer, hand it over, and they carry on. You repeat that exchange as many times as the task needs, and it ends when they say they're finished. The agent loop is exactly that exchange, formalized: call the model, read one field to see whether it's done or wants a tool, act if needed, repeat.

The one field that runs the whole show is stop_reason. After every model reply your code asks a single yes/no question of it: did the model finish (end_turn), or does it want a tool (tool_use)? That's the fork in the road, and it's genuinely the only decision the loop makes. The classic beginner bug is to inspect the text of the reply and guess — "it said the word 'search', so I'll search" — instead of trusting stop_reason. Don't. The model tells you its intent structurally, in that field; read it, branch on it, and never try to parse intent out of prose. Trace the arrows below clockwise and you've understood every agent you'll ever build.

Two exits: the model says it's finished (end_turn), or your step cap trips. Everything in between is: model asks for a tool → you run it → you give back the result → model continues.

Lab 4.1 · Define a tool intermediate

Imagine hiring a sharp new teammate on their very first day. They're capable and eager, but they know nothing about your systems. You hand them a one-line note for each thing they're allowed to do: what it's called, when to reach for it, and exactly what information you need from them to do it. If your note is vague — "handles stuff" — they'll either never use the tool or use it at the wrong moment. If it's precise — "use this whenever a customer asks about a refund; I need the order ID and the amount" — they'll get it right. A tool definition is that note. The model is the new teammate, and everything it knows about your tool is what you wrote in the definition. It cannot see the function body, your comments, or your intentions — only the description and the schema.

That's why this deceptively small block is worth slowing down on. A tool is three things: a name (the identifier the model uses to ask for it), a description (prose telling the model when to use it), and an input_schema (a JSON schema declaring the arguments and their types). The name and schema are plumbing — easy to get right. The description is where the real skill lives, and it's where people under-invest most.

The common mistake is writing the description as documentation instead of as instructions. "Gets the weather for a city" tells the model what the tool is, which it can mostly infer from the name anyway. What it can't infer is the when: should it call this for "is it cold in Paris?" Yes. For "what should I pack for Paris?" Also yes — but only if your description hints that weather is relevant to packing. Modern models are deliberately conservative about calling tools (an unnecessary call costs time and money), so a description that spells out the triggering situations — "Call this whenever the user asks about weather, temperature, or conditions in a specific place" — measurably raises how often the model reaches for it at the right moment. Think trigger conditions, not a dictionary entry. And treat the JSON schema as a contract, not a suggestion: "required": ["city"] genuinely forces the model to supply a city, and an enum constrains it to legal values, so a well-typed schema prevents a whole class of malformed calls before they happen.

tools.pyWEATHER_TOOL = {
    "name": "get_weather",
    "description": (
        "Get the current weather for a city. "
        "Call this whenever the user asks about weather, temperature, "
        "or conditions in a specific place."          # WHEN to use it
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type":"string", "description":"City name, e.g. 'Paris'"},
            "unit": {"type":"string", "enum":["celsius","fahrenheit"]},
        },
        "required": ["city"],
    },
}

def get_weather(city, unit="celsius"):        # the actual implementation
    # In real life: call a weather API. Here, fake it.
    return f"18°{'C' if unit=='celsius' else 'F'} and cloudy in {city}"

tools.pyWEATHER_TOOL = {
    "type": "function",                        # Responses API tags each tool
    "name": "get_weather",
    "description": (
        "Get the current weather for a city. "
        "Call this whenever the user asks about weather, temperature, "
        "or conditions in a specific place."          # WHEN to use it
    ),
    "parameters": {                            # same JSON schema, key is "parameters"
        "type": "object",
        "properties": {
            "city": {"type":"string", "description":"City name, e.g. 'Paris'"},
            "unit": {"type":"string", "enum":["celsius","fahrenheit"]},
        },
        "required": ["city"],
    },
}

def get_weather(city, unit="celsius"):        # the actual implementation
    # In real life: call a weather API. Here, fake it.
    return f"18°{'C' if unit=='celsius' else 'F'} and cloudy in {city}"

Lab 4.2 · Write the loop intermediate

This is the code I wish someone had shown me before I ever touched an agent framework. It's about twenty lines, and it's the entire beating heart of every agent — once you've read it, the frameworks stop being intimidating and become "oh, that's just this, with more logging." So read it slowly; this one lab pays for the rest of the chapter.

The whole thing is a loop with four moves you already understand from the diagram: call the model, check if it's done, run any tools it asked for, feed the results back. Everything else in the code is bookkeeping in service of those four moves. If you keep that skeleton in your head — call, check, run, feed — the details slot into place instead of feeling like ceremony.

Two details are load-bearing, and both are where beginners quietly break their agent. First: after the model asks for a tool, you must append the model's turn to the history verbatim before you add the tool results. The tool_use block has to physically be in the conversation, or the next API call rejects your tool_result as an orphan referring to something that isn't there. Second: every tool_result you send back must carry the exact same tool_use_id the model put on its request — that id is the thread that ties "here's my answer" to "the question you asked." Get either wrong and you'll see a confusing 400 error that has nothing to do with your logic. The walk below narrates the code line by line; the warning box after it collects the three mistakes people make so you can recognize them on sight. One more thing that isn't optional: notice MAX_STEPS and the for step in range(MAX_STEPS) that bounds the loop. An agent without a hard step cap can loop forever — model asks for a tool, gets a result, asks again, on and on — quietly burning real money. Never, ever write an unbounded agent loop; the cap is a seatbelt, not a nicety.

agent.pyfrom anthropic import Anthropic
from tools import WEATHER_TOOL, get_weather
client = Anthropic()

TOOLS = [WEATHER_TOOL]
DISPATCH = {"get_weather": get_weather}     # name -> function
MAX_STEPS = 6                              # hard cap: the loop MUST terminate

def run_agent(user_input):
    messages = [{"role":"user", "content": user_input}]

    for step in range(MAX_STEPS):
        resp = client.messages.create(
            model="claude-opus-4-8", max_tokens=1024,
            tools=TOOLS, messages=messages,
        )

        if resp.stop_reason == "end_turn":        # model is finished
            return next(b.text for b in resp.content if b.type=="text")

        # else: model asked for tool(s). Append its turn verbatim.
        messages.append({"role":"assistant", "content": resp.content})

        results = []
        for block in resp.content:
            if block.type == "tool_use":
                fn = DISPATCH[block.name]
                out = fn(**block.input)             # run the real function
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,          # MUST match
                    "content": str(out),
                })
        # ALL results go back in ONE user message
        messages.append({"role":"user", "content": results})

    return "Stopped: hit step limit."

print(run_agent("What's the weather in Tokyo?"))

It's currently 18°C and cloudy in Tokyo.

agent.pyimport json
from openai import OpenAI
from tools import WEATHER_TOOL, get_weather
client = OpenAI()

TOOLS = [WEATHER_TOOL]
DISPATCH = {"get_weather": get_weather}     # name -> function
MAX_STEPS = 6                              # hard cap: the loop MUST terminate

def run_agent(user_input):
    input_list = [{"role":"user", "content": user_input}]

    for step in range(MAX_STEPS):
        resp = client.responses.create(
            model="gpt-5.5", max_output_tokens=1024,
            tools=TOOLS, input=input_list,
        )

        calls = [o for o in resp.output if o.type == "function_call"]
        if not calls:                           # no tool calls → model is finished
            return resp.output_text

        # else: model asked for tool(s). Append its output items verbatim.
        input_list += resp.output

        for call in calls:
            fn = DISPATCH[call.name]
            args = json.loads(call.arguments)       # arguments arrive as a JSON string
            out = fn(**args)                         # run the real function
            input_list.append({
                "type": "function_call_output",
                "call_id": call.call_id,            # MUST match
                "output": str(out),
            })

    return "Stopped: hit step limit."

print(run_agent("What's the weather in Tokyo?"))

It's currently 18°C and cloudy in Tokyo.

Lab 4.3 · Multiple & parallel tools advanced

Here's the moment the loop you just wrote earns its design. You'd expect that giving the agent a second tool means more code — a bigger loop, extra branches, special handling for "what if it wants both?" It doesn't. You add a tool definition and one line to the dispatch map, and the loop from Lab 4.2 handles it with zero changes. The first time you watch that happen it feels like cheating. It isn't — it's the payoff of having written the loop generically instead of hard-coding one tool.

The reason is worth internalizing, because it's why good agent code stays small as it grows. Your inner loop doesn't say "if the model wants weather, do X; if it wants search, do Y." It says "for every tool the model asked for, look up the function by name and run it." That single generic step — for block in resp.content, dispatch by block.name — is indifferent to how many tools exist or which ones the model picks. Register ten tools and the loop is unchanged; the model simply has ten names to choose from. Think of the dispatch map as a switchboard: the loop is the operator who connects any incoming request to the right line, and adding a new line means adding one entry to the directory, not rebuilding the switchboard.

Two behaviors fall out of this for free, and they're the point of the "advanced" label. The model can chain tools — call get_weather, read the result, then decide it also needs to recommend clothing — which is just multiple trips around the loop, each informed by the last. And it can call tools in parallel — ask for weather in Oslo and search the travel policy in a single turn — because a model reply can contain several tool_use blocks at once. Your loop already runs every block in that turn and returns every result together, so parallel calls "just work." The one mistake that quietly breaks this is splitting those parallel results across separate messages instead of batching them into one — do that and you train the model out of asking for parallel calls at all, because from its point of view the calls didn't come back cleanly. Keep all results for a turn in a single user message, exactly as Lab 4.2 does, and the composition stays effortless.

tools.py (add)SEARCH_TOOL = {
    "name": "search_docs",
    "description": "Search the internal knowledge base. Use when the user "
                   "asks about company policy, products, or procedures.",
    "input_schema": {"type":"object",
        "properties":{"query":{"type":"string"}}, "required":["query"]},
}
def search_docs(query):
    return retrieve_from_ch3(query)      # reuse your RAG retriever!

agent.py (update)TOOLS = [WEATHER_TOOL, SEARCH_TOOL]
DISPATCH = {"get_weather": get_weather, "search_docs": search_docs}

tools.py (add)SEARCH_TOOL = {
    "type": "function",
    "name": "search_docs",
    "description": "Search the internal knowledge base. Use when the user "
                   "asks about company policy, products, or procedures.",
    "parameters": {"type":"object",
        "properties":{"query":{"type":"string"}}, "required":["query"]},
}
def search_docs(query):
    return retrieve_from_ch3(query)      # reuse your RAG retriever!

agent.py (update)TOOLS = [WEATHER_TOOL, SEARCH_TOOL]
DISPATCH = {"get_weather": get_weather, "search_docs": search_docs}

Lab 4.4 · Safety — gates, caps, validation advanced

A demo agent and a production agent run almost identical code — the difference is entirely in this section, and it's the difference between a party trick and something you'd trust near real systems. A chatbot that gives wrong weather is embarrassing. An agent that can send email, delete records, or issue refunds and gets one call wrong is a very different kind of Monday. The instant your tools can change the world rather than just read it, "the model usually gets it right" stops being good enough, because the failures you care about are the rare, expensive, irreversible ones.

The mental shift is from reversible to irreversible. Reading data is reversible — a wrong read costs you a wasted call and nothing more, so let the agent do it freely. But you cannot un-send an email, un-delete a record, or un-spend money. For that class of action the right instinct is the one every serious operations team already lives by: a human confirms before the irreversible thing happens. That's the human-in-the-loop gate — a checkpoint that pauses the agent and asks a person "are you sure?" before running anything on the dangerous list, exactly like a bank app making you re-confirm a large transfer.

The elegant part of the code below is how a denial is handled. When the human says no, the code doesn't raise an exception or crash the run — it feeds the string "DENIED by human. Suggest an alternative." back into the loop as the tool's result. That matters more than it looks: because the denial arrives as data the model can read, the agent stays in its normal loop and simply adapts — it proposes a different course instead of exploding or silently stalling. Returning refusals as data, not exceptions, is the design that keeps a gated agent graceful. The mistake to avoid is over-gating: dump every tool into the destructive set and you'll be tapping y all day for read-only lookups, which trains you to approve on autopilot — and an approval gate you approve reflexively is no gate at all. Put only genuinely harmful, irreversible tools behind the human, and keep the four rails in the checklist below in mind: a step cap, human approval for irreversible actions, validated inputs, and least-privilege credentials — because an agent can do anything its keys allow.

Lab 4.5 · Memory across turns advanced

Talking to the Lab 4.2 agent twice is like talking to someone with no short-term memory. You say "I'm planning a trip to Oslo," it answers helpfully — and then you ask "what's the weather there?" and it has no idea where "there" is, because the moment the previous run_agent call returned, its entire messages list evaporated. Every call started from a blank conversation. That's fine for a one-shot question, and useless for anything that feels like an actual assistant.

The fix is almost anticlimactic, and that's the lesson: the model has no memory of its own — the conversation history is the memory. A language model is stateless; it remembers nothing between calls. What makes it seem to remember is that you resend the whole prior conversation every time. So all "giving the agent memory" means is: don't throw the messages list away between turns. Keep appending to the same list, resend it each call, and the model can "recall" Oslo because Oslo is literally still sitting there in the transcript you handed it. The lab does this by wrapping the loop in a small class whose self.messages lives on the object and survives across .chat() calls. The persistence of that one list is the whole trick — there is no hidden memory store.

That framing immediately tells you the catch. If memory is "resend everything," then a long conversation means resending an ever-growing transcript — and you pay, in tokens and latency, for every past turn on every new call. Eventually the history outgrows the model's context window and the call fails outright. The mistake here is the opposite of forgetting: hoarding. Beginners either build no memory at all, or they keep every token forever and are baffled when a long chat gets slow, expensive, and then breaks. The three levers in the note below — context editing (prune stale tool results), compaction (summarize old history into a short synopsis), and persistent memory (write durable facts to a file or database the agent reads next session) — are how you keep memory bounded. Reach for them when sessions genuinely run long; adding them to a short-lived agent is premature complexity you'll regret maintaining.

stateful_agent.pyclass Agent:
    def __init__(self):
        self.messages = []              # persists across .chat() calls

    def chat(self, user_input):
        self.messages.append({"role":"user","content":user_input})
        for _ in range(MAX_STEPS):
            resp = client.messages.create(model="claude-opus-4-8",
                     max_tokens=1024, tools=TOOLS, messages=self.messages)
            self.messages.append({"role":"assistant","content":resp.content})
            if resp.stop_reason == "end_turn":
                return next(b.text for b in resp.content if b.type=="text")
            results = self._run_tools(resp)
            self.messages.append({"role":"user","content":results})

a = Agent()
print(a.chat("I'm planning a trip to Oslo."))
print(a.chat("What's the weather there?"))   # remembers "Oslo"

stateful_agent.pyclass Agent:
    def __init__(self):
        self.input = []                 # persists across .chat() calls

    def chat(self, user_input):
        self.input.append({"role":"user","content":user_input})
        for _ in range(MAX_STEPS):
            resp = client.responses.create(model="gpt-5.5",
                     max_output_tokens=1024, tools=TOOLS, input=self.input)
            self.input += resp.output   # append output items verbatim
            if not [o for o in resp.output if o.type=="function_call"]:
                return resp.output_text
            self.input += self._run_tools(resp)

a = Agent()
print(a.chat("I'm planning a trip to Oslo."))
print(a.chat("What's the weather there?"))   # remembers "Oslo"

Designing a good tool surface expert

The tools you give an agent shape its behavior more than any prompt you write. I've watched two teams build the "same" agent get wildly different results, and every time the gap traced back to the tool surface — the set of tools, how broad each one is, how they're described — not the model or the system prompt. The prompt is advice; the tools are the world the agent actually lives in. Design that world carelessly and no amount of prompt-tuning rescues it.

The sharpest design tension is broad versus narrow. A broad tool — say, "run any bash command" — gives the agent enormous reach in one definition: it can do almost anything a shell can. But that reach is opaque. You can't easily gate it (which commands are dangerous?), can't validate its inputs (any string is "valid"), can't render its intent to a human, and can't reason about whether two calls are safe to run in parallel. A narrow tool — send_email(to, subject, body) — gives up reach for control: your harness can inspect exactly what's being sent, require approval, validate the address, and log it cleanly. The everyday analogy is a Swiss Army knife versus a labeled toolbox: the knife does everything and you can't tell what someone's about to do with it; the toolbox makes each action explicit. Start broad to explore what the agent needs, then promote to narrow the moment you need control over a specific action.

The mistake that creeps in as a project matures is tool sprawl. Every new capability feels like it deserves its own tool, and before long the agent is choosing among forty of them — at which point the model gets worse, not better, because the description of each tool is context the model must read and weigh on every single call, and near-duplicate tools blur the "when to use it" signal. Keep the set focused and each description crisp; for genuinely large tool libraries, load schemas on demand (tool search) rather than pasting all forty into every request. And carry the read-only-versus-mutating distinction from Lab 4.4 straight into the design: mark read-only tools parallel-safe so they can run concurrently, and gate the mutating ones. The table is your design checklist — walk it for every tool before you ship it.

Common pitfalls expert

Almost every broken agent I've debugged failed for one of a small handful of reasons — the same ones, over and over. That's the good news hiding in this table: agent bugs are not a bottomless pit of novel mysteries. They cluster. Learn to recognize the half-dozen classic failure signatures below and you'll fix in minutes what otherwise costs an afternoon of confused staring at API errors.

It helps to sort them into two buckets, because they fail in very different ways. The first bucket is protocol mistakes — you broke the shape of the conversation the API expects. Forgetting to append the assistant turn before the tool results, mismatching a tool_use_id, or splitting parallel results across messages all land here, and they announce themselves loudly with a 400-style error on the next call. Annoying, but honest: the API tells you immediately that something is malformed, and the fix is mechanical. The analogy is a form rejected for a missing field — irritating, instantly diagnosable.

The second bucket is quieter and more dangerous: judgment mistakes that don't error at all. An agent with no step cap doesn't crash — it runs beautifully, in a loop, spending money until you notice the bill. An agent that trusts its tool arguments blindly doesn't error — it cheerfully deletes the wrong record. And the most strategic mistake of all, building an agent for a task that should have been a plain workflow, produces something that works in the demo and is needlessly slow, costly, and flaky forever after. These don't announce themselves; you have to design against them up front. The rule of thumb that catches most of them: cap every loop, validate every tool input, gate every irreversible action, and before you build the agent at all, ask honestly whether a script would do the job. The table pairs each pitfall with its one-line fix so you can use it as a pre-flight checklist.

Exercises expert

ADD_TOOL = {
    "name": "add",
    "description": "Add two numbers. Call this whenever the user needs a sum.",
    "input_schema": {
        "type": "object",
        "properties": {
            "a": {"type": "number"},
            "b": {"type": "number"},
        },
        "required": ["a", "b"],
    },
}
assert set(ADD_TOOL) == {"name", "description", "input_schema"}
assert ADD_TOOL["input_schema"]["required"] == ["a", "b"]
print("valid tool:", ADD_TOOL["name"])

def get_weather(city, unit="celsius"):
    return f"18°{'C' if unit=='celsius' else 'F'} and cloudy in {city}"

DISPATCH = {"get_weather": get_weather}

class ToolUse:                       # stands in for a tool_use content block
    type = "tool_use"
    id = "toolu_01"
    name = "get_weather"
    input = {"city": "Tokyo"}

block = ToolUse()
fn = DISPATCH[block.name]
out = fn(**block.input)
result = {"type": "tool_result", "tool_use_id": block.id, "content": str(out)}
print(result)
assert result["tool_use_id"] == block.id      # must match the request

MAX_STEPS = 6

def run_agent(user_input, model):
    messages = [{"role":"user", "content": user_input}]
    for step in range(MAX_STEPS):
        resp = model(messages)
        if resp["stop_reason"] == "end_turn":
            return next(b["text"] for b in resp["content"] if b["type"]=="text")
        messages.append({"role":"assistant", "content": resp["content"]})  # verbatim
        results = []
        for b in resp["content"]:
            if b["type"] == "tool_use":
                results.append({"type":"tool_result", "tool_use_id": b["id"],
                                "content": "42"})
        messages.append({"role":"user", "content": results})   # ALL results, ONE message
    return "Stopped: hit step limit."

calls = {"n": 0}
def good_model(msgs):
    calls["n"] += 1
    if calls["n"] == 1:
        return {"stop_reason":"tool_use",
                "content":[{"type":"tool_use","id":"t1","name":"add","input":{}}]}
    return {"stop_reason":"end_turn", "content":[{"type":"text","text":"The answer is 42."}]}

def runaway_model(msgs):             # never says done
    return {"stop_reason":"tool_use",
            "content":[{"type":"tool_use","id":"t","name":"add","input":{}}]}

print(run_agent("add stuff", good_model))
print(run_agent("spin forever", runaway_model))   # cap stops it

def get_weather(city, **_): return f"18C in {city}"
def search_docs(query, **_): return f"results for {query}"
DISPATCH = {"get_weather": get_weather, "search_docs": search_docs}

content = [   # model asked for TWO tools at once
    {"type":"tool_use", "id":"u1", "name":"get_weather", "input":{"city":"Oslo"}},
    {"type":"tool_use", "id":"u2", "name":"search_docs", "input":{"query":"travel policy"}},
]

results = []
for b in content:
    if b["type"] == "tool_use":
        out = DISPATCH[b["name"]](**b["input"])
        results.append({"type":"tool_result", "tool_use_id": b["id"], "content": str(out)})

req_ids = {b["id"] for b in content if b["type"]=="tool_use"}
res_ids = {r["tool_use_id"] for r in results}
assert req_ids == res_ids, "every request needs exactly one matching result"
print("matched ids:", sorted(res_ids))
one_message = {"role":"user", "content": results}   # all in ONE message
print("results in one message:", len(one_message["content"]))

DESTRUCTIVE = {"send_email", "delete_record", "issue_refund"}

def execute_tool(name, args, dispatch, approver):
    if name in DESTRUCTIVE:
        if not approver(name, args):
            return "DENIED by human. Suggest an alternative."   # data, not an exception
    return dispatch[name](**args)

dispatch = {
    "get_weather":   lambda city, **_: f"18C in {city}",
    "delete_record": lambda id, **_: f"deleted {id}",
}

auto_deny    = lambda name, args: False
auto_approve = lambda name, args: True

print(execute_tool("get_weather", {"city":"Oslo"}, dispatch, auto_deny))   # read-only: runs
print(execute_tool("delete_record", {"id":"42"}, dispatch, auto_deny))     # gated: denied
print(execute_tool("delete_record", {"id":"42"}, dispatch, auto_approve))  # gated: approved

# In production the approver reads a real y/N; the denial string flows back as the
# tool_result so the model changes course instead of crashing.

READ_ONLY  = {"kubectl_get", "terraform_plan", "log_search"}
MUTATING   = {"terraform_apply", "kubectl_delete", "scale_deployment"}

def policy(tool):
    if tool in READ_ONLY:
        return {"run": "auto", "parallel_safe": True}
    if tool in MUTATING:
        return {"run": "require_approval", "parallel_safe": False}
    return {"run": "deny_unknown", "parallel_safe": False}   # default-deny

for t in ["kubectl_get", "terraform_apply", "rm_rf_slash"]:
    print(f"{t:16} -> {policy(t)}")

assert policy("terraform_apply")["run"] == "require_approval"
assert policy("kubectl_get")["run"] == "auto"
assert policy("anything_else")["run"] == "deny_unknown"   # unknown tools are refused

Knowledge check check yourself