Debugging Claude Agents: Loops, Bad Tool Calls, Fixes (Anthropic Economic Index)

The Anthropic Economic Index keeps surfacing the same uncomfortable truth: the tasks people actually hand to Claude — coding, data wrangling, drafting, analysis — are exactly the tasks where an agent's failures are most expensive and least visible. When a chatbot gives a wrong answer, you read it and move on. When a Claude agent silently calls the wrong tool, retries forever, or invents a function argument, it can churn through dollars of tokens and leave a half-finished mess in your repo before anyone notices. Debugging agentic systems is a different discipline from debugging code, and most teams learn it the hard way.

This post is a practical field guide to the three failure modes that dominate real agent traces — runaway loops, wrong tool calls, and hallucinated arguments — and how to instrument a Claude Code or Agent SDK system so you can catch and fix them fast.

Key takeaways

• The Economic Index shows agents now do multi-step work, which means failures compound across turns instead of dying in one bad reply.
• The three top failure modes are loops (no progress), wrong tool calls (right intent, wrong tool), and hallucinated args (a tool called with invented parameters).
• Every fix starts with a trace: log every turn's tool name, arguments, and result, not just the final answer.
• Loops are usually a stop-condition bug, not a model bug — add max-step budgets and progress checks.
• Strict tool schemas and required-field validation kill most hallucinated-argument errors before they execute.

Why agent debugging is harder than it looks

A single LLM response is a pure function: prompt in, text out. An agent is a loop. Claude reads context, decides on an action, the runtime executes a tool, the result comes back, and the cycle repeats until some stop condition fires. Each turn mutates state — files change, rows get written, an email queues. That means a bug on turn 4 can be caused by a subtle context error on turn 2, and the only way to see it is to replay the whole trace.

The Anthropic Economic Index frames this well: the highest-value uses of Claude are augmentative, multi-step tasks where a human delegates a chunk of work. The more steps in that chunk, the more surface area for the loop to go sideways. A summarization prompt can't loop forever; an agent told to "fix the failing tests" absolutely can.

So the first rule of agent debugging is that the artifact you debug is not the answer — it is the trace. If you are not logging every turn, you are flying blind.

There's a second, subtler reason agents are hard: they're stochastic. The same prompt can produce a clean run on Monday and a loop on Tuesday because the model sampled a slightly different first action. That means "it worked when I tried it" is not evidence the bug is gone, and a single passing run tells you almost nothing. You debug agents the way you debug flaky distributed systems — by replaying many runs, looking at distributions of behavior rather than single traces, and pinning down the conditions under which the failure reappears.

The three failure modes, and what each one looks like in a trace

Loops. The agent repeats near-identical actions without making progress — re-reading the same file, re-running a command that already failed, or oscillating between two states. In the trace you'll see the same tool name and similar arguments appearing turn after turn with no change in the underlying state. Loops burn tokens and are the single most common reason a run "hangs."

Wrong tool calls. The intent is right but the tool is wrong: Claude calls a read-only search tool when it needed a write tool, or invokes list_files when it meant read_file. These are often caused by overlapping tool descriptions — two tools that sound similar in their schema docstrings.

Hallucinated arguments. Claude calls a real tool but invents a parameter: a column that doesn't exist, a file path it never saw, or an ID it guessed. These execute, fail downstream, and sometimes corrupt state before failing.

flowchart TD
  A["Agent turn starts"] --> B{"Made progress vs last turn?"}
  B -->|No, repeat detected| C["LOOP: cut run, log last 3 turns"]
  B -->|Yes| D{"Tool exists & schema valid?"}
  D -->|No tool match| E["WRONG TOOL: tighten descriptions"]
  D -->|Args fail validation| F["HALLUCINATED ARGS: reject & reprompt"]
  D -->|All good| G["Execute tool"] --> H["Append result to context"] --> A

Instrumenting a Claude agent so you can actually see the bug

The cheapest, highest-leverage thing you can do is structured turn logging. For every step, capture the tool name, the full arguments object, the raw result, the token count, and a hash of the relevant state (e.g., file contents). When something goes wrong, you can diff turn N against turn N-1 and the loop or the bad call jumps out immediately.

Here is a minimal turn-logger you can drop around an Agent SDK tool dispatch. It records each call and flags repeats — the foundation of loop detection.

const seen = new Map();

function logTurn(turn, toolName, args, result) {
  const key = toolName + JSON.stringify(args);
  const count = (seen.get(key) || 0) + 1;
  seen.set(key, count);
  console.log(JSON.stringify({
    turn,
    tool: toolName,
    args,
    repeatCount: count,
    ok: !result?.error,
    bytes: JSON.stringify(result).length
  }));
  if (count >= 3) {
    throw new Error(`Loop suspected: ${toolName} called ${count}x with identical args`);
  }
}

That single guard — abort after three identical calls — eliminates the most expensive class of runaway. Pair it with a hard maxSteps budget on the whole run so even a slow-drifting loop dies before it drains your account.

Common pitfalls

• Vague tool descriptions. If two tools have similar-sounding docstrings, Claude will mix them up. Write descriptions that say exactly when NOT to use a tool, not just when to use it.
• No required-field validation. Letting a tool run with whatever args arrive invites hallucinated parameters. Validate against the schema and reject before execution, returning a clear error Claude can recover from.
• Silent retries. Auto-retrying a failed tool call without changing anything just produces a loop with extra steps. Retries should carry new information.
• Swallowing tool errors. If a tool fails but returns an empty success result, Claude assumes it worked and builds on sand. Surface errors verbatim into the context.
• Debugging the final answer instead of the trace. The answer is the symptom; the bug lives three turns earlier.

A repeatable debugging workflow

1. Reproduce with a fixed seed prompt and capture the full turn-by-turn trace.
2. Scan the trace for repeated (tool + args) pairs — that's your loop signal.
3. For each tool call, check whether the chosen tool matched the intent; mismatches point to overlapping descriptions.
4. Validate every argument against the tool schema; flag any value that wasn't present in prior context as a likely hallucination.
5. Add the narrowest guard that would have prevented the failure — a stop condition, a schema constraint, a sharper description.
6. Replay the trace to confirm the fix, then add it to a regression eval so it never returns.

Choosing the right guard for the failure

Frequently asked questions

What is the most common Claude agent failure mode?

Loops. Because agentic tasks are multi-step, the most frequent expensive failure is an agent repeating an action without making progress. A repeat-detection guard plus a hard step budget prevents nearly all of them and is the first thing to add to any production run.

How do I stop Claude from hallucinating tool arguments?

Define strict JSON schemas with required fields and validate every argument before executing the tool. If a value wasn't present in the prior context, reject the call and return a clear error so Claude can correct itself on the next turn rather than acting on an invented parameter.

Should I retry a failed tool call automatically?

Only if the retry carries new information. Retrying an identical call produces a loop with extra steps. A good pattern is to return the error text into the context and let Claude decide a different action, rather than blindly re-running the same call.

Why debug the trace instead of the final answer?

An agent mutates state across turns, so a wrong final answer is usually the downstream symptom of an earlier bad decision. The trace — every tool name, argument, and result — is the only place the actual root cause is visible.

Bring reliable agents to your phone lines

The same loop-detection and tool-validation discipline that keeps a Claude coding agent honest is what makes a voice agent trustworthy. CallSphere applies these agentic patterns to voice and chat — assistants that answer every call, call tools mid-conversation, and book work around the clock without going off the rails. 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.