Kairox Arch Prep
STUDY NOTES · LESSON 1 OF 12 · 6 MIN READ

The agentic loop: how Claude uses tools

A visual, plain-English explanation of the tool-use loop: stop reasons, tool_result blocks, loop limits and what your code is responsible for.

In 30 seconds

  • Claude never runs your tools. It asks for them; your code runs them and sends the results back.
  • The loop continues while stop_reason is "tool_use" and ends at "end_turn" — or when your code says stop.
  • Ordinary Messages requests are stateless: you resend the conversation, including tool calls and results, every time.
  • Every production loop needs limits in code: turns, cost or time, plus a defined escalation path.
The tool-use loop between your application, Claude and your toolsYour apphistory + toolsClaudeMessages APIYour toolsorders, refunds…Final answerstop_reason: end_turn1 messages + tool definitions2 tool_use (stop_reason: tool_use)3 run it4 tool_result5 donerepeat 1–4 until end_turnYour code counts turns and spend — at the limit, stop and escalate
One turn of the loop. Claude only asks for tools; your code runs them, returns results, and decides when to stop.

What actually happens in one turn

Your application sends Claude the conversation so far and a list of tool definitions. If Claude decides it needs information or an action, its response ends with stop_reason: "tool_use" and contains one or more tool_use blocks — each with a tool name, an input and an ID. Nothing has happened yet. Your code reads those blocks, runs the matching functions, and sends the results back in the next user message as tool_result blocks, one per tool_use ID, placed before any other text.

assistant: tool_use  id=t1  get_order {"order_id": "A-1042"}
user:      tool_result  tool_use_id=t1  {"status": "shipped", "eta": "Nov 28"}

Claude then continues. It may ask for another tool, or answer — stop_reason: "end_turn". If it asked for two tools at once, both results go back together in a single user message.

Why "stateless" matters

With ordinary Messages requests, the API keeps no memory between calls. Each request carries the full history: the user's messages, Claude's earlier turns including its tool_use blocks, and your tool_result blocks. Drop any of them and Claude loses track — or the API rejects a tool call that has no matching result.

Who is responsible for stopping

Claude usually finishes on its own, but malformed data, timeouts or an ambiguous goal can make it call tools again and again. The model cannot be the only safeguard. Your orchestrator should count iterations and track spend, and when a limit is reached it should stop and route the case somewhere useful — usually a person, with the work so far.

Remember: a stop_reason of "max_tokens" means the response was cut off, not that the task is finished.

Errors are results too

When a tool fails, return a tool_result marked as an error with a clear message — what failed and whether retrying is safe. An empty result looks like "no data" and leads Claude to a confident wrong answer.

Part of Domain 1: Agentic Architecture & Orchestration (27% of the exam). Explanations are our own, checked against Anthropic's documentation on November 22, 2026.

Common traps

TrapWhy it failsDo this instead
Letting Claude loop until it decides to stopMalformed inputs can cause endless tool calls and costCap turns and spend in code; escalate at the cap
Sending one tool result per messageEvery tool_use needs its result in the next user messageReturn all results together, one block per ID
Returning an empty result on failureClaude reads it as "nothing found"Return an error result with what failed and whether to retry

Check yourself

Two original practice questions on this lesson. Try them before opening the answers.

Check yourself 1

Scenario: Customer support resolution agent

Your orchestrator receives a response whose stop_reason is "tool_use". The content contains two tool_use blocks. What must the next request to the Messages API contain for the loop to continue correctly?

  1. A. A tool_result for the first call only; Claude will request the second tool again if needed
  2. B. One user message holding a tool_result block for each tool_use_id, placed before any text
  3. C. An assistant message that summarises both tool outputs so Claude can continue from them
  4. D. Two consecutive user messages, each carrying the tool_result for one of the two tool calls
Show answer and explanation

Answer: B. With ordinary Messages requests and client tools, you keep Claude's assistant turn (including its tool_use blocks) in the history, run the tools, and return every result in the next user message: one tool_result block per tool_use_id, placed before any text. Splitting results across messages or omitting one leaves a tool_use without its result, which the API rejects. Tool output is returned by the user role, not summarised in an assistant turn.

Check yourself 2

Scenario: Claude Code for continuous integration

Which statements about the agentic loop on the Messages API are correct? Choose two.

  1. A. Your application runs the requested tools and sends the results in the next request
  2. B. The loop continues while stop_reason is "tool_use" and ends at "end_turn" or a limit
  3. C. Claude keeps earlier tool results between calls, so you only send the newest message
  4. D. For client tools, the API runs your tool code on Anthropic's servers and returns the output
  5. E. A stop_reason of "max_tokens" means Claude finished the task within the token budget
Show answer and explanation

Answer: A and B. With client tools, Claude only requests calls; your code runs them and returns tool_result blocks, then calls the API again. The Messages API is stateless, so the conversation is resent each time. The loop runs while Claude asks for tools and ends at end_turn or an application limit. "max_tokens" means the response was cut off, not that the task is complete.

Keep going