Debugging Claude Agent Orchestration: Loops & Bad Tool Calls

The first time an orchestration system built on Claude goes sideways, it rarely fails loudly. It fails by spending forty thousand tokens calling the same search tool eleven times, each time slightly rephrasing the query, never noticing that the answer it needs isn't in that index at all. Nobody threw an exception. The run just got expensive and slow and produced a confident, wrong summary. Debugging an agent orchestration system is less about stack traces and more about reading intent: figuring out why a capable model made a decision that looked reasonable in the moment but was wrong in context.

This post walks through the failure modes that actually show up when you put an orchestrator and a fleet of subagents into production on Claude — the loops, the wrong tool selections, the hallucinated arguments — and the concrete instrumentation that turns each one from a mystery into a fixable bug.

Why agent bugs don't look like normal bugs

In a traditional program, a bug is a divergence between what the code says and what you meant. In an agentic system the "code" is a probability distribution over next actions, conditioned on a context window you only partially control. The same prompt can succeed on Monday and loop on Tuesday because a tool returned a slightly different payload that nudged the model toward a different branch. That non-determinism is why you cannot debug agents by re-reading the prompt alone — you have to capture the actual transcript of the run: every message, every tool call with its exact arguments, every tool result, and the model's reasoning between them.

The practical consequence is that structured tracing is not optional. Before you fix a single failure mode, instrument the orchestrator to log a typed event for each step: a unique span id, the agent that emitted it, the tool name, the arguments as raw JSON, the result size in tokens, and the latency. Without that, you are guessing. With it, most of the failures below become obvious within a few minutes of reading a trace.

Failure mode one: the runaway loop

Loops are the most common and most expensive failure. They come in two flavors. The first is the retry loop: a tool fails or returns empty, the model tries again with a tiny variation, fails again, and repeats until something — usually a turn budget, if you have one — stops it. The second is the ping-pong loop: two subagents, or an orchestrator and a subagent, hand work back and forth without converging, each politely deferring to the other.

The fix has three layers. First, hard limits: cap the number of turns per agent and the total tool calls per run, and treat hitting the cap as a first-class error you alert on, not a silent truncation. Second, loop detection: hash each (tool name + normalized arguments) pair and refuse, or escalate, when the same hash repeats more than twice — the model is clearly not making progress. Third, and most durable, give the model an explicit exit. A subagent that can return "I could not find this; here is what I tried" will take that off-ramp instead of grinding. Claude follows a clear escape hatch reliably when you describe it in the system prompt.

flowchart TD
  A["Subagent step"] --> B{"Tool returned useful result?"}
  B -->|Yes| C["Advance task state"]
  B -->|No| D{"Same tool+args seen before?"}
  D -->|No| E["Retry with variation"] --> A
  D -->|Yes, twice| F["Loop detected"]
  F --> G{"Turn budget left?"}
  G -->|Yes| H["Escalate to orchestrator"]
  G -->|No| I["Return: stuck + attempts log"]

Failure mode two: the wrong tool call

Wrong-tool errors are quieter than loops and easier to ship to production unnoticed. The model picks search_orders when it should have called search_inventory, gets plausible-looking data back, and reasons confidently from the wrong source. The root cause is almost always ambiguity in the tool surface: two tools whose descriptions overlap, names that don't make the distinction obvious, or a tool whose description promises more than it delivers.

The cure is tool-surface hygiene, treated with the same care you'd give an API design. Each tool's description should state precisely what it does, what it does not do, and when to prefer a sibling tool. Keep the count of tools exposed to any single agent small — a focused subagent with five well-named tools mis-selects far less often than a generalist with thirty. When you genuinely need many tools, that is itself a signal to split the work across subagents, each with a narrow toolset, so the orchestrator's job becomes routing rather than fine-grained selection. Skills help here too: a skill that documents exactly when to reach for a tool sharpens selection without bloating the system prompt.

Failure mode three: hallucinated arguments

The subtlest failure is a correct tool called with invented arguments. The model decides it needs a customer record, calls get_customer(id), and confidently passes an id it pattern-matched from elsewhere in the conversation — an order number, a date, a value it simply made up because the shape looked right. The tool succeeds or 404s, and either way the downstream reasoning is poisoned.

Defend at the boundary. Validate every tool argument against a strict schema before execution and return a precise, actionable error when validation fails — "customer_id must be a 12-char ULID; you passed 'ORD-4471'" teaches the model to correct itself far better than a generic 400. Where an argument must reference a real entity, require the model to have obtained it from a prior tool result rather than constructed it; you can enforce this by tracking which ids appeared in tool outputs and flagging any argument that didn't. And keep arguments small and explicit: tools that take a handful of named, typed fields get hallucinated less than tools that accept a free-form blob the model is invited to fill in creatively.

Reading a trace like a detective

When a run misbehaves, replay its trace from the top and ask three questions at each step. Did the model have the information it needed to make this decision, or was it guessing? Did the tool result actually contain what the model then claimed it contained? And did this step move the task forward or just spin? Most bugs reveal themselves to one of those three questions. A model guessing means a context or retrieval gap upstream. A result the model misread means your tool output format is too noisy — tighten it. A step that didn't advance means a missing exit condition.

Build a lightweight replay harness early. Being able to take a captured trace, swap in a fixed prompt or tool description, and re-run just the failing segment turns debugging from speculation into experiment. It also becomes the seed of your eval set: every production failure you reproduce is a test case you never want to regress on.

Frequently asked questions

How do I tell a loop from legitimate retrying?

Legitimate retries make progress — different arguments, new information entering the context, the task state advancing. A loop repeats the same (tool, normalized-arguments) pair or shuttles work between agents without the underlying state changing. Hashing the action and watching for repeats is the cleanest programmatic signal.

Why does Claude sometimes hallucinate tool arguments even with good prompts?

Usually because the required value isn't actually present in the context window, so the model fills the gap with a plausible-looking token. The fix is upstream: make sure the entity id or value the tool needs was returned by an earlier tool call, and validate arguments at the boundary so invented ones bounce back with a corrective error.

What's the single most useful thing to instrument first?

A per-step structured trace with tool name, raw arguments, result token count, and latency. Almost every failure mode in agent orchestration becomes diagnosable once you can read exactly what the model did, in order, with the real data it saw.

Take agentic debugging to your phone lines

CallSphere runs these same debugging disciplines — traced tool calls, loop guards, schema-validated arguments — inside voice and chat agents that handle real customer conversations, use tools mid-call, and book work around the clock. See how it holds up live 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.