CONCEPT The four invariants of a valid tool_result
Returning a tool result looks trivial, but the API enforces a strict contract. Violate any part and you get a hard HTTP 400 — not a soft degradation. Memorize these four invariants; the exam tests them directly.
| Invariant | Rule | Violate it → |
|---|---|---|
| Matching id | tool_use_id must equal the id of the tool_use block it answers. | 400 |
| User role | The tool_result lives in a user turn, never assistant. | 400 |
| One user message | ALL results for one assistant turn go in a single user message. | 400 / missing result |
| Alternation | Roles must alternate user → assistant → user; no two same-role turns in a row. | 400 |
tool_result block is shaped
{"type":"tool_result", "tool_use_id": <id>, "content": <str or blocks>}. Add
"is_error": true to signal the tool failed — Claude reads it as a failure and can retry or adapt,
rather than treating the payload as a valid answer.DIAGRAM The id must match, the role must be user
tool_use { id: "toolu_A1", name, input } Note over App: run the tool App->>API: user turn
tool_result { tool_use_id: "toolu_A1" } Note over App: ✅ id matches + role=user API-->>App: end_turn (final answer) App-->>App: ❌ tool_use_id "toolu_XX"? → 400 App-->>App: ❌ put in assistant turn? → 400 App-->>App: ❌ two user turns in a row? → 400
CODE Building the tool_result turn
Success path, the is_error path, and returning results for every tool_use in the
same assistant turn in ONE user message.
tool_uses = [b for b in resp.content if b.type == "tool_use"] results = [] for tu in tool_uses: try: out = run_tool(tu.name, tu.input) results.append({ "type": "tool_result", "tool_use_id": tu.id, # MUST match the tool_use id "content": out, # str, or a list of content blocks }) except Exception as e: results.append({ "type": "tool_result", "tool_use_id": tu.id, "content": f"Error: {e}", "is_error": True, # tells Claude the tool FAILED }) # ONE user message carrying ALL results from that assistant turn. messages.append({"role": "user", "content": results}) resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=messages, )
tool_use id in an assistant turn must be answered in
the next single user turn.EXAM TRAPS
tool_use_id doesn't equal the
tool_use.id it answers (typo, wrong index, stale id). → HTTP 400.tool_result in an
assistant turn. Results are always a user turn. → HTTP 400.is_error: true so Claude adapts, not a fabricated "OK".PRACTICE
Q1 · Claude returned two tool_use blocks. How many user messages should carry the results?
One. All results from a single assistant turn go in one user message, as a list of two
tool_result blocks — each with its own matching tool_use_id. Splitting them 400s.
Q2 · Your DB tool timed out. What do you send back?
A tool_result with the matching tool_use_id, an explanatory
content, and "is_error": true. Claude then knows the call failed and can retry, choose a
different tool, or explain the failure — instead of trusting a fake result.
Q3 · Name the three ways to get a 400 from a tool_result.
(1) Mismatched tool_use_id, (2) wrong role (assistant instead of user),
(3) non-alternating roles — including splitting one turn's results across multiple user messages.