Claude Parallel Tool Use: My Agent Loop Crashed on 388 of 1,200 Runs

A developer's codebase Q&A agent failed 388 of 1,200 runs with HTTP 400 errors because its loop only handled the first tool_use block, while Claude's parallel tool use returns multiple tool calls per turn. The initial fix of stripping orphaned tool_use blocks eliminated crashes but dropped the agent's eval score to 38/50; executing every tool_use block and returning all tool_results together in one user message raised it to 46/50.

My codebase Q&A agent ran 1,200 times in its first week. 388 of those runs died with the same HTTP 400. The other 812 worked fine, which is the worst possible ratio: too low to look like a broken deploy, too high to ignore. The cause was one line I'd copied from my own earlier prototype: next b for b in resp.content if b.type == "tool use" . It grabs the first tool call. Claude parallel tool use means there often isn't just one. Then I "fixed" it in a way that made the crashes disappear and quietly made the agent dumber. This post covers all of it, plus the numbers from the version that finally worked. tool use blocks tool result in the asyncio.gather , return is error: true instead of dropping them. disable parallel tool use when tool order truly matters. It cost me 0.8 extra turns per run. It answers questions about a mid-sized Python monorepo. Three tools: read file , grep , list dir . Python SDK, a Claude Sonnet model, a plain while stop reason == "tool use" loop. Nothing exotic. A typical question is "where do we retry failed webhook deliveries?" The model greps, reads two or three files, answers. On a good run that's 3 or 4 round trips. Here's the loop body I shipped on day one: resp = client.messages.create model=MODEL, max tokens=2048, tools=TOOLS, messages=messages if resp.stop reason == "tool use": block = next b for b in resp.content if b.type == "tool use" result = run tool block.name, block.input messages.append {"role": "assistant", "content": resp.content} messages.append {"role": "user", "content": {"type": "tool result", "tool use id": block.id, "content": result} } It passed every manual test I ran. My manual tests were all simple questions, and simple questions get one tool call at a time. Because it can, and it's usually the smart move. When the model already knows it needs retry.py and webhooks/sender.py , asking for both in one turn saves a full round trip. Parallel tool use is on by default in the Messages API. So a response to "compare how the two webhook senders handle timeouts" looks like this: content: text: "I'll read both sender implementations." tool use: id=toolu 01A..., name=read file, input={path: "webhooks/sender.py"} tool use: id=toolu 01B..., name=read file, input={path: "webhooks/legacy sender.py"} stop reason: "tool use" My loop ran toolu 01A , appended the full assistant content both blocks , and sent back one result. The next request failed with: 400 invalid request error: messages.4: tool use ids were found without tool result blocks immediately after: toolu 01B... That's the rule: every tool use in an assistant message needs a tool result with the matching tool use id in the next user message. No partial credit. My first patch was the obvious shortcut. If the API complains about orphaned tool use blocks, remove them before appending the assistant turn: first = next b for b in resp.content if b.type == "tool use" kept = b for b in resp.content if b.type = "tool use" or b.id == first.id messages.append {"role": "assistant", "content": kept} Crashes went to zero. I felt great for about a day. Then I ran my 50-question eval set hand-labeled, each with a known correct file and line range . Score: 38/50. The v4 loop described below scores 46/50 on the same set. Reading transcripts made it obvious. From the model's point of view, its own history now said it had asked for one file. So it did one of two things: Editing the assistant's own past turns is gaslighting your agent. It plans based on what it believes it already did. Execute every tool use block, then return every result together in a single user message. Here's the loop I run now: python import asyncio from anthropic import AsyncAnthropic client = AsyncAnthropic async def run one block : try: out = await run tool block.name, block.input return {"type": "tool result", "tool use id": block.id, "content": out} except Exception as e: return {"type": "tool result", "tool use id": block.id, "content": f"{type e . name }: {e}", "is error": True} async def step messages : resp = await client.messages.create model=MODEL, max tokens=2048, tools=TOOLS, messages=messages messages.append {"role": "assistant", "content": resp.content} if resp.stop reason = "tool use": return resp calls = b for b in resp.content if b.type == "tool use" results = await asyncio.gather run one b for b in calls assert {r "tool use id" for r in results} == {c.id for c in calls} messages.append {"role": "user", "content": list results } return None Three details matter more than they look. One user message, not several. I briefly tried sending one user message per result. Beyond being awkward, Anthropic's tool use docs warn that splitting results across messages teaches the model to stop making parallel calls in that conversation. You lose the speedup you just paid to support. tool result blocks go first. If you want to add text to that user message I append a short "N tool calls remaining in budget" note , it goes after the results. Text first and the API rejects it. Errors are results. A FileNotFoundError on one of three reads used to kill the whole turn. Now the model gets is error: true with the message, and it usually corrects the path on the next turn. That alone recovered 2 of my 50 eval questions. The assert is cheap insurance. If someone later adds a tool that silently returns None and gets filtered out, the loop fails loudly in my process instead of with a 400 from the API. In my setup, about one tool turn in seven. After the fix, I logged every turn across another 1,200 runs: stop reason: "tool use" read file across six test fixtures grep + That 14.2% is the number that explains the 32% crash rate. A run has several tool turns, so the odds that at least one of them goes parallel are much higher than the per-turn rate. Your number will differ with your tools and prompts. Read-heavy tools with obvious fan-out invite more parallelism than a single "run SQL" tool would. Only if your tools have ordering dependencies. Setting tool choice={"type": "auto", "disable parallel tool use": True} makes the model emit at most one tool use per turn, which makes the naive loop technically correct. I tested it as a fourth variant on the same question set. All four, side by side: | Loop version | Crashed runs | Eval score | Turns/run | Input tokens/run | Median latency | |---|---|---|---|---|---| | v1: first block only | 388 / 1,200 | n/a | n/a | n/a | n/a | | v2: strip extra blocks | 0 | 38/50 | 4.9 | ~41K | 26.5s | | v3: disable parallel tool use | 0 | 45/50 | 4.4 | ~36K | 24.9s | | v4: all results, gathered | 0 | 46/50 | 3.6 | ~29K | 18.2s | The token column surprised me most. Every extra turn re-sends the whole conversation as input. Fewer round trips means less re-reading, so v4 used about 29% fewer input tokens per run than v2, on top of being faster because the file reads overlap. Where I would turn parallelism off: an agent with write file and run tests . If the model fires both in one turn, asyncio.gather gives you no ordering guarantee, and tests may run against the old file. For side-effecting tools, either disable parallel use or execute the blocks sequentially in the order they appear. Grep your code for these patterns. Each one is a version of my bug: next b for b in ... if b.type == "tool use" resp.content -1 or resp.content 1 used as "the tool call" tool use id variable that's a single string instead of a list try/except around tool execution that continue s without appending a result resp.content before appending it to history If your SDK version ships a tool runner helper, it handles the matching for you. I still like owning the loop, because then I can log the parallel rate, which turned out to be the most useful number in this whole debugging session. Claude parallel tool use returns multiple tool use blocks in a single response, and the API requires a tool result for every one of them, matched by tool use id , in the next user message. Loops that handle only the first block crash with a 400; loops that strip the extra blocks stop crashing but feed the model a false history and give worse answers. Execute every call, return all results together in one user message with failures marked is error: true , and reserve disable parallel tool use for tools whose order matters. In my agent that meant zero crashes, 46/50 on eval instead of 38/50, and runs that were 31% faster. Written by the developer behind Preterview https://preterview.com/en , an interview prep platform.