CONCEPT The message-shape contract Claude enforces
Returning a result isn't just "put a tool_result somewhere." The Messages API enforces a strict
shape for the turn that follows tool use, and violating it returns an invalid_request_error
(HTTP 400) — the whole request is rejected. These are the four contract rules; break any one and the loop
stops.
| Rule | Requirement | Break it → |
|---|---|---|
| Every call answered | Each tool_use needs a matching tool_result | 400: "tool_use ids were found without tool_result blocks immediately after" |
| IDs must match | tool_use_id must equal a real tool_use.id from the prior assistant turn | 400: unmatched / absent tool_use_id |
Results go in a user turn | tool_result blocks belong in a user message, immediately after the assistant's tool-use message | 400: results in the wrong role / a message in between |
| Results come FIRST | In that user message, all tool_result blocks precede any text | 400 (esp. with an unresolved server tool): text before results ends the turn early |
CONCEPT The four failures, concretely
- Missing a result. Claude called three tools; you returned two. The third
tool_usehas no answer → 400. (This is the #1 cause — every call must be answered, even failed ones, withis_error: true.) - Mismatched / absent
tool_use_id. A typo'd or invented ID matches notool_useblock → 400. The ID is the join key; it must be copied exactly. - Result in an assistant turn. Putting a
tool_resultin anassistantmessage, or inserting any message between the tool-use turn and the result turn, breaks "immediately after" → 400. - Interleaving text incorrectly. Text before the
tool_resultblocks in the user message ends the turn early. If the assistant turn also called a server tool with no result yet, the request 400s naming the unresolved server tool. Text after all results is fine.
DIAGRAM Where the 400s come from
(unresolved server tool)"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class OK ok; class E1 bad; class E2 bad; class E3 bad; class E4 bad;
CODE The 400-triggering shape vs. the valid one
// ❌ 400 — text BEFORE the tool_result in the user message { "role": "user", "content": [ { "type": "text", "text": "Here are the results:" }, // text first → invalid { "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." } ] } // ✅ valid — all tool_result blocks first, optional text AFTER { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." }, { "type": "text", "text": "What should I do next?" } // text after → fine ] }
And the completeness rule — one result per call, even the failed one:
// assistant called toolu_01 AND toolu_02; you must answer BOTH { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01", "content": "ok" }, { "type": "tool_result", "tool_use_id": "toolu_02", "is_error": true, "content": "Not executed: preceding call failed." } ] } // omitting toolu_02 → 400
TRADE-OFFS Hand-rolled loop vs. SDK Tool Runner
✅ SDK Tool Runner
- Formats results & placement for you — contract 400s avoided
- Handles the multi-call turn automatically
- Less loop code to get wrong
⚙️ Manual loop
- Full control over batching / ordering / error handling
- But: you own the contract — every rule above is yours to enforce
tool_result responses and the multi-call turn correctly on your behalf.EXAM TRAPS
tool_result for any
tool_use is a 400. Answer every call — use is_error: true for the ones that failed
or weren't run.tool_result in an assistant message (or slipping a message
between the tool-use turn and the result). → Results go in a user message immediately after the
assistant's tool-use turn.PRACTICE
Q1 · Name the four ways a tool-result turn can 400.
(1) A tool_use with no matching tool_result; (2) a
tool_use_id that matches no call (typo/invented/absent); (3) the result placed in an assistant turn or
not immediately after the tool-use turn; (4) text interleaved before the tool_result blocks
(fatal when a server tool is unresolved).
Q2 · You get "tool_use ids were found without tool_result blocks immediately after." What do you check?
Completeness (every tool_use.id answered), placement (results in the very next
user message, nothing in between), and ordering (all tool_result blocks before any
text). One of those three is wrong.
Q3 · Can you add a sentence of narration in the same user message as the results?
Yes — but only after all tool_result blocks. Text before them ends the turn
early and 400s when the assistant turn also called an unresolved server tool.