The tool-use round trip, from the API documentation

The exam guide describes the agentic loop in prose. This is the same loop as the API documents it: the exact message shapes, the exact field names, and the full set of values that decide whether your loop runs again.

One turn, in full

A client tool round trip is three messages. Your request defines the tool; Claude answers with a tool_use block; you run the tool and send a tool_result back.

You send messages plus a tools array. Each tool carries a name, a description, and an input_schema.
Claude replies with stop_reason: "tool_use" and one or more tool_use blocks. Each block has an id, a name, and an input object.
You append two messages — the assistant turn verbatim, then a user turn whose content is a tool_result block carrying tool_use_id and content. The tool_use_id must match the id from step 2.
You send again. Claude uses the result to answer.

Where the code runs

The documentation splits tools by where they execute, and it is worth holding because it decides whether you write a handler at all.

Kind	Runs	You handle results?
Client tools	In your application	Yes — you send `tool_result`
Anthropic-schema client tools	In your application	Yes — schema is published, execution is yours
Server tools	On Anthropic's infrastructure	No — results come back in the same response

bash and text_editor are client tools with Anthropic-published schemas. web_search, web_fetch and code_execution are server tools.

Every stop_reason value

This is the set the loop branches on. The exam guide keys two of them; the API returns seven.

Value	Meaning	What you do
`end_turn`	Claude finished naturally	Use the response
`tool_use`	Claude is calling a tool	Run it, append the result, send again
`max_tokens`	Hit the `max_tokens` you set	Treat as truncated; raise the limit or continue
`stop_sequence`	Emitted one of your `stop_sequences`	Read the `stop_sequence` field for which
`pause_turn`	Server-tool loop hit its iteration limit	Send the assistant content back to continue
`refusal`	Declined on safety grounds	Read `stop_details`; retry on a fallback model
`model_context_window_exceeded`	Filled the context window before `max_tokens`	Treat the response as truncated

Two details the documentation is specific about: refusal returns HTTP 200, not an error, and the pause_turn iteration limit for server-side tool loops defaults to 10.

tool_choice

tool_choice constrains a single request. The default is {"type": "auto"}, which lets Claude decide whether to call a tool at all.

Setting	Guarantee
`auto`	None — Claude may return text instead
`any`	A tool will be called, but not which one
`tool` with a `name`	That specific tool is called
`none`	No tool is called

disable_parallel_tool_use: true limits a turn to at most one tool call.

Strict tool use

Adding strict: true to a custom tool definition makes Claude's calls match your schema exactly. That eliminates a class of shape error and does nothing about semantics — a schema-valid call can still put the right value in the wrong field.

Sources

Tool use overview — https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview (retrieved 2026-08-30)
Handling stop reasons — https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons (retrieved 2026-08-30)