Reference: the tool-use round trip
Claude Certified Architect - Foundations (CCAR-F) › Domain 1: Agentic Architecture & Orchestration
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
messagesplus atoolsarray. Each tool carries aname, adescription, and aninput_schema. - Claude replies with
stop_reason: "tool_use"and one or moretool_useblocks. Each block has anid, aname, and aninputobject. - You append two messages — the assistant turn verbatim, then a user turn whose content is a
tool_resultblock carryingtool_use_idandcontent. Thetool_use_idmust match theidfrom 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)