Debugging Claude Agents: Loops, Bad Tool Calls, Hallucinated Args (Cowork Plugins Across Enterprise)

The first time you watch a Claude agent dig itself into a hole, it is mesmerizing in the worst way. You ask it to reconcile two spreadsheets, and instead of finishing, it reads the same file four times, calls a tool with an argument that does not exist, apologizes to itself, and tries again. Nothing crashed. There is no stack trace. The run just burned forty thousand tokens and produced confident nonsense. Debugging agents is not like debugging functions, because the bug is rarely in your code — it is in the loop between the model's reasoning and the tools you gave it.

This post is a practical guide to the three failure modes that dominate real Claude Code and Cowork deployments across an enterprise: runaway loops, wrong tool calls, and hallucinated arguments. For each, we will look at why it happens with Claude specifically, how to see it, and how to stop it without lobotomizing the agent.

Why agent bugs hide so well

A traditional bug is deterministic: the same input produces the same wrong output, and a debugger lets you step through it. An agent failure is a trajectory — a sequence of model turns, tool calls, and observations that drifts off course somewhere in the middle. The same prompt can succeed nine times and loop on the tenth, because the model sampled a slightly different first step and the rest cascaded from there.

The most useful mental shift is to stop debugging the prompt and start debugging the transcript. Every Claude agent run is a list of messages: user input, assistant text, tool_use blocks, and tool_result blocks. When something goes wrong, the answer is almost always visible in that sequence — a tool returned an error the model ignored, an argument was malformed, or the same observation appeared three turns in a row. If you are not logging the full message list with tool inputs and outputs, you are debugging blind. Make that the first thing you fix.

Failure mode one: the runaway loop

Loops are the signature agent failure. They come in two flavors. The first is the retry loop: a tool keeps failing, the model keeps calling it the same way, and neither side gives up. The second is the oscillation loop: the agent toggles between two actions — read file A, read file B, read file A — because no single step makes the goal feel closer, so the model never commits.

flowchart TD
  A["Agent turn starts"] --> B{"Repeat of last tool call?"}
  B -->|No| C["Execute tool"]
  B -->|Yes| D{"Repeat count > 2?"}
  D -->|No| C
  D -->|Yes| E["Inject loop-break note into context"]
  E --> F{"Still looping?"}
  F -->|No| C
  F -->|Yes| G["Halt run & surface transcript"]
  C --> H["Return observation to Claude"]

The detection logic is simpler than it looks. Keep a short history of recent tool calls as normalized tuples of name plus arguments. If the identical tuple appears more than twice in a sliding window, you are looping. The cheap fix is a hard turn cap — Claude Code and the Agent SDK both let you bound the number of agent iterations, and you should always set it. The better fix is to feed the loop back to the model: when you detect repetition, inject a short system note like "You have called read_file on report.csv three times with the same result. Do not call it again; use the data you already have or stop and explain what is blocking you." Claude responds well to being told it is stuck, because it usually genuinely had not noticed.

Failure mode two: wrong tool calls

Wrong tool calls are when the model reaches for the right capability with the wrong tool, or the wrong capability entirely — calling a search tool when it should call a database query, or invoking a destructive delete when the task only needed a read. With Claude this usually traces back to tool descriptions that overlap or under-specify. If two MCP tools have fuzzy, similar descriptions, the model has no reliable basis to choose between them.

The fix lives in the tool definitions, not the prompt. Write each tool's description as if it were the only documentation a new engineer would ever read: state exactly what it does, when to use it, when not to use it, and what it returns. Name tools by intent ("search_orders_by_customer") rather than by implementation ("query"). For dangerous actions, gate them — require a confirmation step or a separate higher-privilege tool — so a wrong call is contained rather than catastrophic. When you see a recurring wrong-tool pattern in transcripts, the remedy is almost always to disambiguate the two tools' descriptions, not to add another paragraph of prompt instructions the model will skim.

Failure mode three: hallucinated arguments

Hallucinated arguments are the subtlest. The model calls the right tool but invents a parameter value: a customer ID it never saw, a date format the API rejects, a field name that does not exist in your schema. Claude is strong at structured output, so when this happens it is usually because the tool's input schema was loose enough to permit the hallucination.

Tight JSON schemas are your best defense. Mark required fields as required, constrain enums, and add format hints. When an argument must come from a previous tool result, say so in the description: "order_id must be a value returned by search_orders; do not construct it." Validate every tool input before execution and return a clear, model-readable error on failure — "order_id 'ORD-FAKE' was not found; valid IDs come from search_orders" teaches the model far more than a generic 400. Claude reads tool errors and corrects course, but only if the error explains what was wrong.

Building a debugging workflow you can repeat

Ad hoc debugging does not scale across a team running dozens of plugins. Build a small harness instead. Record every run's full transcript with timestamps, token counts per turn, and tool latencies. When a run misbehaves, you want to replay it: feed the same messages back and watch where the trajectory forks. Tag transcripts by failure mode so you can see whether loops or hallucinated args are your dominant cost.

The highest-leverage habit is turning every production failure into a regression case. When an agent hallucinates an argument in a real run, save that transcript, reduce it to the minimal context that triggers the bug, and add it to your eval suite. Over a few weeks this turns debugging from firefighting into a flywheel: each bug you fix becomes a test that stops it from coming back. Agent debugging is the discipline of reading transcripts, reproducing trajectories, and tightening the tool contracts that shape what Claude can and cannot do.

Frequently asked questions

How do I stop a Claude agent from looping forever?

Set a hard cap on agent turns so a run can never spin indefinitely, then add loop detection that flags when the same tool call repeats more than twice. On detection, inject a note telling Claude it is stuck and to use existing data or stop. The turn cap is your safety net; the injected note is what usually breaks the loop cleanly.

Why does Claude call the wrong tool?

Almost always because two tools have overlapping or vague descriptions, leaving the model no clear basis to choose. Rewrite each tool description to state precisely when to use it and when not to, name tools by intent, and gate destructive actions behind confirmation so a wrong choice is contained.

What causes hallucinated tool arguments?

Loose input schemas. When a parameter is unconstrained, the model may invent a plausible-looking value. Use strict JSON schemas with required fields and enums, tell the model which arguments must come from prior tool results, and validate inputs with clear error messages so Claude can self-correct.

What should I log to debug agents effectively?

Log the complete message list for every run — user turns, assistant text, tool_use blocks with full arguments, and tool_result blocks — plus per-turn token counts and tool latencies. The full transcript is where nearly every agent bug is visible; without it you are guessing.

Bringing agentic AI to your phone lines

CallSphere takes these same debugging disciplines — loop guards, tight tool contracts, transcript-level visibility — and applies them to voice and chat agents that answer every call, use tools mid-conversation, and book work around the clock. See the live system 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.