Debugging Claude agents: loops, bad tool calls, fixes (Rethinking How We Build)

The first time a Claude agent burns through fifty turns re-reading the same file and never finishing, you stop trusting the demo and start respecting the engineering. Single-shot prompts fail loudly: you see a bad answer and move on. Agents fail in slow motion. They keep going, taking actions, spending tokens, and occasionally doing damage, all while looking superficially busy. Debugging an agent is less like reading a stack trace and more like reviewing a flight recorder after the plane lands somewhere it shouldn't have.

This post is a practical guide to the failure modes that actually show up when you ship agents built on Claude Code, the Claude Agent SDK, or your own orchestrator over the Anthropic API. I'll name the patterns, explain why each one happens at the model and harness level, and give you the instrumentation that turns a baffling run into a fixable bug.

Why agent bugs feel different from normal bugs

An agent loop is a feedback system: the model reads context, picks an action, the action changes the world, and the new state feeds back into context. Every failure mode is some pathology of that feedback. The model isn't crashing — it's making locally reasonable decisions that compound into a globally wrong trajectory. That makes the usual debugging instinct, "set a breakpoint and inspect a variable," almost useless. The bug lives in the sequence, not in any single step.

The single most valuable thing you can build before debugging anything else is a complete, replayable trace of every turn: the full message list sent to Claude, the exact tool definitions in scope, the model's response including tool-call blocks, the raw tool results returned, and the token counts. If you can't see the literal bytes that went into the model on turn 23, you are guessing. Most teams discover their hardest agent bug is actually a context bug — something upstream poisoned the conversation — and you cannot see that without the raw trace.

The loop: when an agent can't tell it's done

Looping is the signature agent failure. The agent repeats a near-identical action — re-listing a directory, re-fetching a page, re-asking the same sub-question — and never converges. Almost always the cause is that the agent cannot perceive the effect of its last action, so from its point of view nothing has changed and the obvious next move is to try again.

Three concrete culprits dominate. First, a tool returns an error as a 200-style success with an empty body, so the model sees "no result" and retries forever. Second, the result is too large and gets truncated mid-structure, so the model never sees the field that would tell it to stop. Third, the system prompt never defines a termination condition, so "done" is undefined and the agent optimizes for activity. The fix for all three is to make state changes legible: return explicit success/failure markers, summarize large results instead of truncating them, and give the agent an unambiguous stop signal — a final-answer tool it must call, or a checklist it marks complete.

flowchart TD
  A["Agent turn"] --> B{"Made progress since last turn?"}
  B -->|Yes| C["Continue plan"]
  B -->|No| D{"Same action 2+ times?"}
  D -->|No| C
  D -->|Yes| E["Loop detected"]
  E --> F["Inject diff & constraints into context"]
  F --> G{"Resolved?"}
  G -->|Yes| C
  G -->|No| H["Halt & escalate to human"]

Notice the guard rail in the diagram: a harness-level loop detector. You hash the last few actions, and if the agent repeats one without measurable progress, you intervene rather than waiting for the turn cap. Intervention can be as simple as injecting a system message that says, in effect, "You already ran this and got X; that path is exhausted, try something else," which is often enough to break Claude out of the rut.

Wrong tool calls and hallucinated arguments

The second family is malformed action. The agent picks a plausible-but-wrong tool, invents an argument that doesn't exist, or passes a value in the wrong shape. With modern Claude models, raw JSON-syntax errors are rare; the real problem is semantic. The model fills a required customer_id field with a value it never actually retrieved, because the schema demanded a string and the model is helpful to a fault.

The root cause is almost always ambiguous tool design, not model failure. If two tools have overlapping descriptions — search_orders and find_order — the model will guess, and it will guess wrong about a third of the time. If a parameter description says "the order ID" without saying where order IDs come from, the model will hallucinate one rather than admit it doesn't have it. Tighten the contract: make tool names and descriptions mutually exclusive, mark which parameters must come from a prior tool result, and validate arguments in the tool wrapper before execution. When validation fails, return a specific, instructive error — "customer_id must be a value returned by lookup_customer; you have not called that yet" — so the model self-corrects on the next turn instead of repeating the mistake.

Context drift and the poisoned conversation

A subtler failure: the agent does fine for fifteen turns, then quietly goes off the rails. This is context drift. As the conversation grows, early instructions get buried, a stale tool result keeps influencing decisions, or summarization silently dropped the one constraint that mattered. The model is now reasoning over a corrupted picture of the world, and every downstream action inherits the corruption.

To catch drift, log a compact snapshot of working state each turn — current goal, open subtasks, key facts retrieved — and diff it across turns. The turn where the snapshot first diverges from reality is your crime scene. Structurally, keep durable instructions pinned at the top of the system prompt where they survive context pressure, prefer fresh tool reads over relying on aged results deep in the history, and when you compact long histories, treat that compaction as code worth testing, because a lossy summary is a silent bug factory.

Building an agent debugger you'll actually use

Good agent debugging is mostly good observability bought in advance. At minimum, capture a per-run timeline of turns with token usage, store every raw tool input and output, and tag each turn with the model's stated reasoning so you can see intent versus action. Add three derived signals: a progress metric (did world-state change?), a repetition metric (action similarity to recent turns), and a cost metric (tokens per useful step). Most pathologies announce themselves in one of those three before they cause visible damage.

The highest-leverage habit is replay. When a run misbehaves, you should be able to re-feed the exact recorded context into Claude and watch the decision again, then mutate one variable — sharpen a tool description, fix a truncated result, add a stop condition — and see if the trajectory changes. That tight replay loop turns agent debugging from archaeology into engineering, and it's the difference between shipping agents you trust and agents you babysit.

Frequently asked questions

Why does my Claude agent keep repeating the same tool call?

Almost always because it cannot perceive that the last call had an effect. Check whether the tool returned an empty or truncated result, whether errors are being swallowed as fake successes, and whether the agent has any explicit termination condition. Add a harness-level loop detector that injects the prior result and forbids the repeated action.

How do I stop an agent from hallucinating tool arguments?

Make tool contracts unambiguous and validate before executing. Mark which parameters must originate from a prior tool result, give each parameter a precise description, and return instructive errors when validation fails so the model corrects itself rather than guessing again on the next turn.

What is the single most useful thing to log when debugging agents?

The complete raw context sent to the model on every turn — the full message list, the tool definitions in scope, and the verbatim tool results. Most hard agent bugs are context bugs, and you cannot diagnose what you cannot see byte-for-byte.

How many turns should an agent be allowed before I force a halt?

Set a hard turn and token budget per run as a safety net, but treat hitting it as a bug, not a feature. A well-instrumented agent should detect its own lack of progress and escalate to a human long before it exhausts a generous cap.

From debugging agents to debugging conversations

The same instrumentation that tames a coding agent tames a voice or chat agent on the phone. CallSphere runs multi-agent assistants that answer every call and message, call tools mid-conversation, and book work around the clock — with the trace logging and loop guards described here baked in so failures get caught, not shipped. See it 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.