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

3.4 · Parallel Tool Calls & Result Ordering

Many tools, one user turn

CONCEPT One assistant turn can hold several tool_use blocks

By default (on by default for Claude 4 models), Claude can emit multiple tool_use blocks in a single assistant turn — "check weather in SF and NYC and the time in both" becomes several calls at once, with stop_reason: "tool_use". You decide how to run them: concurrently (asyncio.gather, Promise.all), sequentially, or a mix — the API doesn't prescribe an execution order. What the API does require is how you return the results.

CONCEPT The one hard rule: all results, one user message

Return one tool_result for every tool_use block, all together in the single next user message. Each result is matched to its call by tool_use_id, so the order of the results inside that message is flexible — but every call must have a result, and they must all be in the same user turn.

✅ Correct — one user message with all results:
[ {assistant: [tool_use_1, tool_use_2]}, {user: [tool_result_1, tool_result_2]} ]
⚠️ Wrong — a separate user message per result:
[ {assistant: [tool_use_1, tool_use_2]}, {user: [tool_result_1]}, {user: [tool_result_2]} ]
This isn't just untidy — splitting results across messages silently trains Claude to stop making parallel calls in future turns.
🔑 Order among results is by tool_use_id, not position — but completeness and single message are mandatory. Miss a result and the request 400s (see 3.5).

CONCEPT Ran them sequentially and one failed? Still return a result for the rest

Execution strategy is yours, but the result contract is fixed. If you batch sequentially and stop on the first failure — or a parallel call fails because its prerequisite hadn't finished — still return a tool_result for every unrun call, marked is_error: true with a brief reason. Don't drop it; a missing result breaks the turn.

DIAGRAM Fan out, then converge into one user turn

flowchart TD A["assistant turn:
tool_use A · tool_use B · tool_use C"] --> RUN{"Run them (your choice)"} RUN -->|"concurrent / sequential / mixed"| EX["Execute A, B, C"] EX --> ONE["ONE user message:
tool_result A + B + C
(matched by tool_use_id)"] ONE --> NEXT["Claude continues"] EX -.->|"a call failed / not run"| ERRR["Still include its result
is_error: true"] ERRR --> ONE SPLIT["❌ separate user msg per result"] -.->|"trains Claude to
stop parallelizing"| BAD["🔴 parallel use decays"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class ONE ok; class BAD bad;

CODE Collect every result into a single user message

# Claude's turn held several tool_use blocks.
tool_uses = [b for b in response.content if b.type == "tool_use"]

tool_results = []
for tu in tool_uses:
    try:
        out = run_tool(tu.name, tu.input)   # run concurrently if you prefer
        tool_results.append({ "type": "tool_result",
                              "tool_use_id": tu.id, "content": out })
    except ToolError as e:
        # Still return a result for the failed/unrun call.
        tool_results.append({ "type": "tool_result",
                              "tool_use_id": tu.id,
                              "content": str(e), "is_error": True })

messages.append({ "role": "assistant", "content": response.content })
messages.append({ "role": "user", "content": tool_results })   # ALL results, ONE message

The parallel-results user message on the wire:

{ "role": "user", "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "SF: 68F, partly cloudy" },
    { "type": "tool_result", "tool_use_id": "toolu_02", "content": "NYC: 45F, clear" },
    { "type": "tool_result", "tool_use_id": "toolu_03",
      "is_error": true, "content": "Not executed: get_time timed out." }
] }

TRADE-OFFS Parallel vs. serial execution (your side)

✅ Run in parallel

  • Lowest latency for independent, read-only calls
  • Fewer round trips to Claude

⚙️ Run sequentially

  • Right when calls share state or have ordering deps
  • Stop-on-first-failure is a valid strategy…
  • …but you still return a result for every call
Either way, the result contract is identical: one result per call, all in one user message. Execution order is a performance choice; the message shape is not.

EXAM TRAPS

Trap: Sending each result in its own user message. → Split results silently train Claude to stop parallelizing, and can 400. Put all results in one user message.
Trap: Dropping the result for a call you didn't run. → Every tool_use needs a matching tool_result; return is_error: true for skipped/failed calls, don't omit them.
Trap: Thinking result order must mirror call order. → Results are matched by tool_use_id, so ordering is flexible — completeness and single-message are what matter.
Trap: Reaching for a top-level "no parallel" flag. → It's disable_parallel_tool_use: true inside tool_choice, not a top-level request parameter.

PRACTICE

Q1 · Claude emits three tool_use blocks in one turn. How many user messages do you send back, and how many results?

One user message containing three tool_result blocks — one per call, matched by tool_use_id. Splitting them across messages degrades future parallel tool use and risks a 400.

Q2 · You ran the batch sequentially and call #2 failed, so you skipped #3. What goes in the reply?

Results for all three: the real output for #1, an is_error: true result for #2, and an is_error: true result for #3 ("Not executed: preceding call failed."). Never omit a call's result.

Q3 · How do you turn parallel tool use off, and where does the flag live?

Set disable_parallel_tool_use: true inside the tool_choice object. With type: "auto" it caps Claude at one tool call per turn; with any/tool it forces exactly one.