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

> Source: <https://dev.to/ji_ai/claude-parallel-tool-use-my-agent-loop-crashed-on-388-of-1200-runs-4i28>
> Published: 2026-10-02 09:02:05+00:00

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.*