D2 · Tool Design & MCP › Cluster 3 · Tool Results & Error Handling

3.5 · Tool-Result Contract Failures (400s)

Why tool loops break

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.

RuleRequirementBreak it →
Every call answeredEach tool_use needs a matching tool_result400: "tool_use ids were found without tool_result blocks immediately after"
IDs must matchtool_use_id must equal a real tool_use.id from the prior assistant turn400: unmatched / absent tool_use_id
Results go in a user turntool_result blocks belong in a user message, immediately after the assistant's tool-use message400: results in the wrong role / a message in between
Results come FIRSTIn that user message, all tool_result blocks precede any text400 (esp. with an unresolved server tool): text before results ends the turn early

CONCEPT The four failures, concretely

🔑 Diagnostic: if you see "tool_use ids were found without tool_result blocks immediately after," check completeness (all IDs answered), placement (user turn, right after the assistant turn), and ordering (results before text).

DIAGRAM Where the 400s come from

flowchart TD A["assistant turn: tool_use × N"] --> CHK{"Your next user message"} CHK -->|"result for every id"| R1{"IDs all match a tool_use?"} CHK -->|"a call unanswered"| E1["🔴 400: tool_use without tool_result"] R1 -->|"yes"| R2{"In a user turn, immediately after?"} R1 -->|"no / typo / invented"| E2["🔴 400: mismatched tool_use_id"] R2 -->|"yes"| R3{"tool_result blocks before any text?"} R2 -->|"assistant turn / msg in between"| E3["🔴 400: wrong placement"] R3 -->|"yes"| OK["🟢 Loop continues"] R3 -->|"text first"| E4["🔴 400: text before results
(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
If you're hitting contract 400s repeatedly, the Tool Runner exists precisely to format tool_result responses and the multi-call turn correctly on your behalf.

EXAM TRAPS

Trap: Answering only the calls that succeeded. → A missing 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.
Trap: Putting a 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.
Trap: Leading the user message with explanatory text. → Tool_result blocks come first; text before them ends the turn early and 400s when a server tool is still unresolved. Text after is OK.
Trap: Reading "tool_use ids were found without tool_result blocks immediately after" as a Claude bug. → It's the contract talking: a call is unanswered or your results are misplaced / mis-ordered. Fix the shape.

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.