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.
[ {assistant: [tool_use_1, tool_use_2]}, {user: [tool_result_1, tool_result_2]} ][ {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.
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
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
EXAM TRAPS
tool_use needs a
matching tool_result; return is_error: true for skipped/failed calls, don't omit them.tool_use_id, so ordering is flexible — completeness and single-message are what matter.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.