NOTES / AGENTS

Tool calling

How a model asks for an action. The request, the structured call, the result sent back, and where the tool actually runs.

UPDATED 18 NOV 2026#agents#tools#function-calling#claude-api

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:

  1. Send a request with your tools array and the user message.
  2. Claude replies with stop_reason: "tool_use" and one or more tool_use blocks.
  3. Run each tool and format the outputs as tool_result blocks.
  4. Send a new request with the original messages, the assistant reply, and a user message containing the tool_result blocks.
  5. Repeat from step 2 while the stop reason is tool_use.

Diagram: sequence between application and model: request with tool schemas, reply with tool_use, application runs the tool, tool_result sent back, final reply with end_turn

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: an assistant message with a tool_use block and a following user message with a matching tool_result block linked by id

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: client tools run in your application; server tools run on the provider's infrastructure

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 bash and text_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_use blocks, and each needs its own tool_result1.

Sources

  1. [1]How tool use works — Anthropic, Claude Platform docsPARAPHRASED
  2. [2]Tool use with Claude — Anthropic, Claude Platform docsPARAPHRASED
  3. [3]A practical guide to building agents — OpenAI · 2025FURTHER READING

© Ashish Kumar. All rights reserved. Quoted and cited material belongs to its owners. How I attribute sources.

Product, company and framework names are trademarks of their respective owners. Mentioning them does not imply affiliation or endorsement.