Tool calling
How a model asks for an action. The request, the structured call, the result sent back, and where the tool actually runs.
The core idea
A language model only produces text. Tool calling is the convention that lets that text be a structured request: “run this function with these arguments.” The model cannot run your code, so each tool call is a round trip. The model asks, you execute, you report back, and the model continues1.
Anthropic’s documentation puts a useful boundary on this: the model never receives your implementation. It sees only the schema you supplied and the result you returned1. That boundary is why tool descriptions matter so much (see Tool design).
The round trip
The canonical shape in Anthropic’s docs is a loop keyed on the stop reason1:
- Send a request with your tools array and the user message.
- Claude replies with
stop_reason: "tool_use"and one or moretool_useblocks. - Run each tool and format the outputs as
tool_resultblocks. - Send a new request with the original messages, the assistant reply, and a user message containing the
tool_resultblocks. - Repeat from step 2 while the stop reason is
tool_use.
Diagram: my own, following the steps in 1.
What is in the messages
In Anthropic’s API, tools are part of the ordinary message structure: messages hold arrays of content blocks, including text, tool_use and tool_result2. A tool_use block carries an id, the tool name and the input. The result goes back in the next user message, tied to the call by that id12.
Diagram: my own and illustrative. It shows the shape described in 1 and 2, not an exact payload.
Other providers use different field names but the same pattern: a declared schema, a structured call, a result returned by your code. OpenAI’s practical guide treats tools in the same way, as the APIs or systems an agent uses to act, and describes data, action and orchestration tools as typical groupings3.
Where the tool runs
Tools differ mainly by where the code executes2.
Diagram: my own, based on the client and server tool split in 2.
- Client tools include your own functions and Anthropic-defined schemas such as
bashandtext_editor. Your application runs them and sends back the result2. - Server tools, such as web search, web fetch and code execution, run on Anthropic’s infrastructure, so you see the results without handling execution2.
For client tools, the loop above is yours to run. The SDKs offer a tool runner that executes your tools and returns results automatically, which saves writing the round trip by hand2.
When the loop exits
The loop continues only while the stop reason is tool_use. Any other stop reason, such as end_turn, max_tokens, stop_sequence or refusal, means Claude produced a final answer or stopped for another reason your application should handle1. That is the entry point to Stopping conditions and budgets.
Notes for implementers
- Treat the tool result as untrusted input. It re-enters the model’s context, which is a route for prompt injection.
- Standardised tool servers are the subject of MCP.
- Parallel tool calls exist: one reply can hold several
tool_useblocks, and each needs its owntool_result1.
Sources
- [1]How tool use works — Anthropic, Claude Platform docsPARAPHRASED
- [2]Tool use with Claude — Anthropic, Claude Platform docsPARAPHRASED
- [3]A practical guide to building agents — OpenAI · 2025FURTHER READING