CONCEPT Two block types, joined by an id
Tool use is a contract between two content blocks. Claude emits a
tool_use block (in an assistant turn); you reply with a matching
tool_result block (in a user turn). The link between them is the
id.
| Block | Role | Key fields |
|---|---|---|
tool_use | assistant | id (e.g. toolu_…), name, input |
tool_result | user | tool_use_id (must equal the tool_use.id), content, optional is_error |
tool_result.tool_use_id must exactly match the
tool_use.id it answers. This is how Claude pairs a result to the call that produced it — order
alone is not enough.CONCEPT The four rules the contract enforces
- Matching ids. Each
tool_resultcarries thetool_use_idof the call it answers. - User role.
tool_resultblocks live in ausermessage — never assistant. - Answer every call. If an assistant turn has multiple
tool_useblocks (parallel tool use), your next user message must return atool_resultfor every one of them, all in a single user message. - Ordering.
tool_resultblocks should come first in that user turn, before any other content.
tool_result for even one of several parallel tool_use
blocks — or splitting results across separate user messages — is an error and quietly trains Claude to stop
making parallel calls.tool_result with
"is_error": true and an informative message. Claude reads it and adapts (retry, ask, or route
around).DIAGRAM The id binds the pair
id: toolu_A1
name, input"] TU2["tool_use
id: toolu_B2
name, input"] end subgraph U["user turn (ONE message)"] TR1["tool_result
tool_use_id: toolu_A1
content"] TR2["tool_result
tool_use_id: toolu_B2
is_error: true"] end TU1 -->|"matched id"| TR1 TU2 -->|"matched id"| TR2 classDef use fill:#e7f1ff,stroke:#4a90d9,color:#1a3a5a; classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef err fill:#f8d7da,stroke:#dc3545,color:#721c24; class TU1 use; class TU2 use; class TR1 ok; class TR2 err;
CODE A matched tool_use → tool_result exchange
The assistant turn holds the tool_use; the following user turn returns every
tool_result — one ok, one flagged is_error — with matching ids.
# --- assistant turn Claude produced (stop_reason: "tool_use") --- { "role": "assistant", "content": [ {"type": "text", "text": "I'll check the weather and the time."}, {"type": "tool_use", "id": "toolu_A1", "name": "get_weather", "input": {"location": "SF"}}, {"type": "tool_use", "id": "toolu_B2", "name": "get_time", "input": {"tz": "Pacific"}} ] } # --- your reply: ONE user message, a result for EVERY tool_use --- { "role": "user", "content": [ {"type": "tool_result", "tool_use_id": "toolu_A1", "content": "15 °C, partly cloudy"}, {"type": "tool_result", "tool_use_id": "toolu_B2", "content": "Timezone service unavailable.", "is_error": true} # failed — flag it, don't drop it ] }
TRADE-OFFS Signaling failure two ways
✅ tool_result with is_error: true
- Claude sees the failure and can recover in-loop
- Keeps the contract intact (every
tool_useanswered) - The error message steers the next attempt
⚠️ Dropping the result / raising outside the loop
- An unanswered
tool_usebreaks the request - Claude gets no signal to adapt — it just stalls
- Server-tool errors are the exception: they arrive as result blocks with an error, not exceptions
EXAM TRAPS
id instead of tool_use_id. → The
tool_use block has id; the tool_result references it via
tool_use_id. They must be equal.tool_use blocks. → You must return a
tool_result for every tool_use in the turn, all in one user
message.is_error: true
and a message. Silence is worse than a reported error.PRACTICE
Q1 · How is a tool_result linked to the call it answers?
Via tool_use_id: the tool_result's tool_use_id must
exactly equal the id of the tool_use block it responds to. Positional order alone
is not the link.
Q2 · Claude returns three tool_use blocks in one turn. What must your reply look like?
A single user message containing three tool_result blocks — one
per tool_use_id. Every call must be answered, and all results go in that one user turn (results
first, before other content).
Q3 · A tool throws. How do you report it inside the contract?
Return a tool_result for that tool_use_id with
"is_error": true and an informative content message. Claude reads the error and
adapts — retry, ask for clarification, or take another path. Don't drop the block.