CONCEPT tool_use is the "keep looping" signal
When stop_reason == "tool_use", the model has decided it needs a tool before it can finish.
The response's content is a list of blocks: some may be text
(the model thinking aloud), and one or more are tool_use blocks — each with an id,
a name, and an input dict. Your job is a fixed four-step cycle.
| Step | Action | Detail |
|---|---|---|
| 1 | Append the WHOLE assistant turn | messages.append({"role":"assistant","content": resp.content}) — the entire content list, text blocks included. |
| 2 | Extract every tool_use block | There can be more than one in a single turn (parallel tool calls). |
| 3 | Run each tool; build a tool_result | tool_result.tool_use_id MUST match the block's id. |
| 4 | Send results back in a user turn | All tool_result blocks go in one user message; call the API again. |
response.content
(not just the tool_use block), and tool_result.tool_use_id must equal the tool_use.id.
A mismatch or a dropped block is a 400-class error.DIAGRAM The tool_use cycle
(role: assistant, content: resp.content)"] B --> C{"iterate content blocks"} C -->|text block| D["(optional) log / show thinking"] C -->|tool_use block| E["run tool(name, input)
→ result"] E --> F["build tool_result
tool_use_id = block.id"] D --> G F --> G["collect all tool_result blocks"] G --> H["append ONE user turn
(role: user, content: [tool_result, ...])"] H --> I([call messages.create again → loop]) classDef loop fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; classDef act fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b; class A,I loop; class E,F act;
CODE The tool_use branch (handles multiple calls)
Note the loop over all blocks — a single turn may contain several tool_use blocks, and
every one needs a matching tool_result.
def handle_tool_use(resp, messages): # 1) Append the WHOLE assistant turn (text + tool_use blocks). messages.append({"role": "assistant", "content": resp.content}) # 2) + 3) Run EVERY tool_use block; collect results. results = [] for block in resp.content: if block.type != "tool_use": continue # skip text/thinking blocks output = run_tool(block.name, block.input) # your dispatch results.append({ "type": "tool_result", "tool_use_id": block.id, # MUST match the tool_use id "content": output, }) # 4) Send ALL results back in ONE user turn, then loop. messages.append({"role": "user", "content": results}) return messages # caller re-invokes messages.create()
tool_result turn, the next
stateless request carries the full context: the model sees what it asked for and what came back.TRADE-OFFS One tool per turn vs. parallel tool_use
✅ Handle all blocks in a turn
- Model can request several tools at once → fewer round-trips
- Lower latency for independent lookups
- Correct: every
tool_usegets itstool_result
⚠️ Only handling the first block
- Leaves
tool_useblocks without results → API error next turn - Silently drops work the model asked for
- Breaks as soon as the model parallelizes
EXAM TRAPS
tool_use block instead of the whole
resp.content. → You lose accompanying text blocks and can desync the turn. Append the
entire content list.tool_result in an assistant turn. → Tool results are the
user's turn (you are speaking on the environment's behalf). Role must be user.tool_use blocks. Loop over all of them; each needs a matching tool_result.tool_result.tool_use_id must equal the originating
tool_use.id. Copy it verbatim; don't regenerate.PRACTICE
Q1 · The model returns a text block AND two tool_use blocks. What goes back to the API?
First append the whole assistant turn (text + both tool_use blocks). Then run both tools and
append one user turn containing two tool_result blocks, each with a
tool_use_id matching its tool_use. Then call again.
Q2 · Your next request fails with an error about an unresolved tool call. Likely cause?
You handled only the first tool_use block and left another without a matching
tool_result, or an ID didn't match. The API requires every tool_use in the prior
assistant turn to be answered.
Q3 · After appending tool_result, do you set stop_reason yourself to keep looping?
No — you never set stop_reason. You just call messages.create again with the
updated messages; the next response carries its own stop_reason
(possibly end_turn now, or another tool_use).