Debugging Claude Multi-Agent Systems: Loops & Bad Tool Calls

The first time a multi-agent system fails on you, it rarely fails loudly. A single Claude agent that goes wrong throws an obvious error or returns nonsense you can spot in one read. An orchestrator coordinating five subagents fails quietly: one subagent silently returns a half-finished result, the orchestrator trusts it, and twenty tool calls later you have an answer that is confidently, expensively wrong. Debugging these systems is less about reading stack traces and more about reconstructing a conversation between agents that you never directly observed.

If you build with the Claude Agent SDK or run parallel subagents in Claude Code, you will meet the same handful of failure modes again and again. This post is a working engineer's guide to the three that cost the most time — runaway loops, wrong tool calls, and hallucinated arguments — and the instrumentation that lets you catch them in minutes instead of hours.

Why multi-agent failures are harder to see

In a single-agent run, the entire reasoning trace lives in one transcript. You scroll, you find the bad turn, you fix the prompt. In a multi-agent system the failure is distributed across processes. The orchestrator's view of reality is whatever its subagents reported back, and a subagent only reports a summary, not its full transcript. So the orchestrator can be working from a lossy, optimistic compression of what actually happened.

This creates a specific debugging trap: the symptom appears in one agent, but the root cause lives in another. An orchestrator that produces a wrong final answer may be reasoning perfectly over bad inputs. Before you touch the orchestrator prompt, you have to ask which subagent handed it a lie. That means your logging has to preserve the boundary — which agent said what, with which tool result, at which step — or you will spend your evening guessing.

Failure mode one: the agent that won't stop

Loops are the most common and most expensive multi-agent failure. A subagent calls a search tool, gets an ambiguous result, calls the same search tool with a slightly reworded query, gets the same ambiguous result, and repeats. Each turn looks locally reasonable. Nothing errors. The run just burns tokens until it hits a turn limit or your budget.

Loops usually come from one of three sources: a tool that returns the same unhelpful result for any input, a goal the agent literally cannot satisfy with the tools it has, or missing memory of what it already tried. The fix starts with detection. Track a rolling hash of each agent's recent tool calls and arguments; if the same call repeats more than twice, that is your signal to intervene rather than wait for the budget to run out.

flowchart TD
  A["Subagent turn"] --> B["Hash tool name & args"]
  B --> C{"Seen this hash > 2x?"}
  C -->|No| D["Execute tool, continue"]
  C -->|Yes| E{"Progress since last loop?"}
  E -->|Yes| D
  E -->|No| F["Inject break-loop note"]
  F --> G["Force summarize & return to orchestrator"]
  D --> A

The break-loop intervention matters as much as detection. When you catch a loop, do not just kill the agent — inject a system note telling it what it has already tried and asking it to either change approach or report that it is stuck. A well-instructed Claude subagent will usually escalate honestly when told it is repeating itself, and an honest "I cannot find this" is far cheaper than a fortieth identical search.

Failure mode two: the wrong tool, confidently chosen

Wrong tool calls are subtler than loops because the run often completes successfully. The agent had a tool that fit, ignored it, and used a worse one — or it picked a tool whose name sounded right but whose contract it misunderstood. With a dozen MCP tools exposed to a subagent, the model's tool-selection accuracy degrades, and the failures are silent.

Two things drive most wrong-tool errors: overlapping tool descriptions and too many tools in scope. If two tools have descriptions that could each plausibly answer the same request, Claude will sometimes pick the wrong one, and which one it picks can vary run to run. The remedy is to write tool descriptions that include explicit "use this when" and "do not use this for" guidance, and to scope each subagent to the smallest set of tools it actually needs rather than handing every agent the full registry.

To debug these, log every tool call with the agent's stated reasoning for choosing it, then build a small confusion matrix from real transcripts: which tool was correct, which was chosen. The pairs that get confused most often point straight at descriptions you need to sharpen or tools you should not have given that agent at all.

Failure mode three: hallucinated arguments

The most dangerous failure is the hallucinated argument: the agent calls the right tool but invents a parameter value. It passes a customer ID that does not exist, a date in the wrong format, or a field name it assumed the API had. Because the tool call is structurally valid, your code happily executes it, and the damage depends entirely on what that tool does.

Defense here is layered. First, make every tool's input schema strict and validate at the boundary — reject unknown fields, enforce enums, and require IDs to match a known pattern before any side effect runs. Second, return rich, specific errors when validation fails: "customer_id 99812 not found; valid IDs come from the lookup_customer tool" teaches Claude to self-correct on the next turn far better than a bare 400. Third, for any tool with real consequences, gate it behind a confirmation step or a dry-run mode so a hallucinated argument fails safe instead of mutating production data.

Building the observability you actually need

You cannot debug what you cannot replay. The single highest-leverage investment for multi-agent debugging is structured, per-agent tracing: a unique run ID, parent-child links between orchestrator and subagents, and a record of every prompt, tool call, tool result, and returned summary with timestamps and token counts. Store it so you can reconstruct the full tree for any run a user complains about.

With that in place, most debugging becomes mechanical. You open the trace tree, find the agent whose output first went wrong, and look at exactly what it saw. Nine times out of ten the bug is upstream of where the symptom appeared — a truncated tool result, a subagent that returned an optimistic summary, or a prompt that gave the agent a goal it could not reach. The trace turns a mystery into a lookup.

Frequently asked questions

How do I stop a Claude subagent from looping forever?

Set a hard turn limit as a backstop, but rely on active loop detection: hash each agent's tool calls and arguments, and when the same call repeats without progress, inject a note telling the agent what it already tried and asking it to change approach or report being stuck. That converts a silent budget burn into a fast, honest escalation.

Why does my agent call the wrong tool when it has many tools?

Tool-selection accuracy drops as the number of in-scope tools grows and as their descriptions overlap. Scope each subagent to the minimum tools it needs, and write descriptions with explicit "use when" and "do not use for" guidance. Logging the agent's stated reason for each tool choice makes the confusable pairs obvious.

What is the best defense against hallucinated tool arguments?

Strict input validation at the tool boundary plus specific, instructive error messages. Reject unknown fields and malformed IDs before any side effect, and return errors that name the correct source of valid values so Claude can self-correct. Gate consequential tools behind dry-run or confirmation steps so a bad argument fails safe.

Where should I start when an orchestrator produces a wrong answer?

Start with the subagents, not the orchestrator. The orchestrator reasons over the summaries its subagents return, so a wrong final answer often means a subagent handed it bad input. Use per-agent tracing to find the first point where an agent's output diverged from reality, then debug there.

Bringing reliable agents to your phone lines

CallSphere takes these same debugging and reliability patterns and applies them to voice and chat — multi-agent assistants that answer every call, call tools mid-conversation, and fail safe when something goes sideways. See how it works at callsphere.ai.

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.