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

The first time a multi-agent system fails in production, it rarely fails loudly. A single agent crashing throws a stack trace you can read. A coordinated set of Claude subagents instead drifts: one subagent keeps re-reading the same file, another calls a tool with an argument it invented, and the orchestrator dutifully keeps spending tokens because, from its narrow vantage point, work still appears to be happening. By the time you notice, you have a run that took eleven minutes and produced nothing useful. Debugging these systems is its own discipline, and the failure modes are surprisingly predictable once you know where to look.

This post walks through the failure modes that show up again and again when teams build orchestrator-subagent systems on Claude Code and the Claude Agent SDK, and how to instrument a run so the cause is obvious instead of buried.

Why multi-agent failures are harder to see

In a single-agent loop, you can read the whole transcript top to bottom and reconstruct what the model was thinking. In a multi-agent system, the orchestrator's transcript only contains summaries handed back by subagents. The interesting evidence — the tool calls, the intermediate reasoning, the moment a subagent went off the rails — lives inside child transcripts the parent never fully sees. A debugging definition worth keeping: a multi-agent failure is any outcome where the system's emergent behavior diverges from the sum of what each agent was individually instructed to do. The bug is usually not in one agent; it is in the seam between them.

That is why the single most valuable thing you can do is make every agent's full action log durable and queryable. Log each tool call with the agent ID, the tool name, the exact arguments, the result size, and a hash of the result. When something goes wrong, you query for repetition, for argument anomalies, and for which agent first produced a value that propagated downstream. Without that log you are guessing.

Failure mode one: the loop that never converges

Loops are the most common pathology. A subagent reads a file, decides it lacks information, reads the same file again, and repeats. Sometimes two agents loop against each other — agent A asks agent B for clarification, B asks A, and neither has the authority to terminate. The model is not broken; it simply has no stopping signal that it trusts.

flowchart TD
  A["Subagent starts task"] --> B["Call tool"]
  B --> C{"New info gained?"}
  C -->|Yes| D["Update working state"]
  C -->|No| E["Increment no-progress counter"]
  D --> F{"Goal met?"}
  E --> G{"Counter > limit?"}
  G -->|No| B
  G -->|Yes| H["Abort & escalate to orchestrator"]
  F -->|No| B
  F -->|Yes| I["Return result"]

The fix is a no-progress detector, not a raw step cap. Track a hash of the agent's working state — the set of facts it has gathered — and increment a counter whenever a full tool call produces no change to that hash. After three or four no-progress turns, abort the subagent and escalate. A raw step cap alone is too blunt; it kills legitimately long tasks while letting a tight two-step loop run to the limit. The state-progress signal distinguishes a stuck agent from a busy one.

For agent-to-agent loops, give exactly one party the authority to terminate the exchange and a hard turn budget for the conversation. Mutual politeness — both agents waiting for the other to decide — is a classic deadlock, and the cure is asymmetry: a designated decider.

Failure mode two: wrong tool calls

The second category is calling the right tool for the wrong reason, or the wrong tool entirely. A subagent tasked with reading data calls a write tool because the names are similar. Or it calls a search tool when it already had the answer in context, burning a turn. These bugs trace back to tool design more often than to the model. When two tools have overlapping descriptions, Claude has to guess, and guessing is where errors enter.

The defense starts in the tool definitions. Each tool's description should state not just what it does but when to use it and, crucially, when not to. Mutually exclusive tools should say so explicitly. Narrow the surface area handed to each subagent: a research subagent does not need write tools in scope at all, and removing them removes a whole class of mistakes. Least privilege is a debugging strategy as much as a security one — a tool that is not available cannot be called wrongly.

When a wrong call does happen, you want the log to show it immediately. Tag each tool result with whether it was a read or a mutation, and flag any mutation made by an agent whose role was supposed to be read-only. That single assertion catches a large fraction of cross-wiring bugs at the moment they occur instead of three steps later.

Failure mode three: hallucinated arguments

The most insidious failure is a tool call with a plausible but fabricated argument. Claude calls a lookup function with an ID that looks valid but was never returned by any previous step — it was synthesized to fill a slot. The tool may even succeed, returning data for the wrong entity, and now everything downstream is quietly corrupted.

The most reliable defense is provenance. Validate that every non-constant argument traces back to a value that actually appeared in a prior tool result within the same run. If an agent passes an order ID, that ID should be findable in some earlier search output; if it is not, reject the call and force the agent to fetch the value properly. This is strict, but it converts a silent semantic error into a loud, catchable one. Schema validation on tool inputs helps with shape, but provenance checks catch the harder case where the shape is right and the value is invented.

Building a reproducible debugging loop

You cannot debug what you cannot replay. Capture each run as a sequence of inputs and tool results so you can re-feed the exact same tool outputs to a fresh agent and watch where it diverges. Because Claude is non-deterministic, run the suspicious case several times; a bug that appears in one of three runs is a tail behavior you still need to handle, not a fluke to ignore. Pin model versions during a debugging session so you are not chasing a behavior change and a code change at once.

Finally, separate the question "did an agent fail?" from "did the system fail?". A subagent that aborts cleanly and escalates is working as designed. The failures that matter are the ones where the orchestrator accepted a bad result as good. Add a verification pass — a cheap Claude Haiku check or a deterministic assertion — between any subagent's output and the orchestrator's acceptance of it, and most silent corruption stops at that gate.

Frequently asked questions

How do I tell an infinite loop from a legitimately long task?

Track whether the agent's working state changes between turns, not just how many turns have passed. A long task keeps acquiring new facts; a loop keeps producing the same state. Abort on consecutive no-progress turns, and reserve the raw step cap as a final backstop, not the primary signal.

What is the single most useful thing to log?

Every tool call with the agent ID, tool name, exact arguments, and a hash of the result. That one stream lets you detect repetition, trace argument provenance, and find which agent first introduced a bad value. Most multi-agent debugging is a query over this log.

How do I catch hallucinated tool arguments?

Enforce provenance: every non-constant argument must trace to a value that appeared in an earlier tool result in the same run. Reject calls whose arguments cannot be traced, which turns a silent wrong-entity lookup into an immediate, debuggable rejection.

Should I debug subagents in isolation or in the full system?

Both. Isolate a subagent by replaying the exact tool results it received to confirm its own logic, then test it in the full system to catch seam bugs — bad handoffs, summary loss, and orchestrators accepting flawed output. Seam bugs only appear when agents run together.

Bringing agentic AI to your phone lines

CallSphere runs the same multi-agent discipline on live voice and chat — agents that answer every call, call tools mid-conversation, and hand off cleanly without looping or inventing data. See it working 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.