Debugging Claude Agents: Loops, Bad Tool Calls, Args

The first time you watch a Claude agent quietly burn through forty turns trying to read a file that does not exist, you stop trusting demos and start respecting traces. Agentic systems fail in ways classic software does not: there is no stack trace, the "bug" is often a single ambiguous sentence in a tool description, and the same prompt can succeed nine times and spiral on the tenth. This post is a debugging field guide for the three failure modes that account for most broken runs on Claude — repeating loops, wrong tool calls, and hallucinated arguments — written under a zero-trust assumption: never assume the model did the right thing, prove it from the transcript.

Zero trust here is not a security slogan, it is a debugging discipline. Treat every tool call the agent emits as a claim that must be verified against the actual tool result before you let the run continue. Most of the pain below comes from teams trusting the model's narration ("I have now updated the record") instead of the structured tool result that says otherwise.

Why agent debugging is different from debugging code

A normal program is deterministic enough that a failing test points at a line. A Claude agent is a loop: the model reads context, decides on a tool call, you execute it, you feed the result back, and it decides again. The failure is rarely in one line of your code — it is in the conversation. The model picked the wrong action given what it could see. So your debugger is not a breakpoint, it is the full message history: system prompt, every tool definition, every tool call with its exact arguments, and every tool result the model actually received.

The single most useful habit is to log that history verbatim and replay it. When a run goes wrong, dump the ordered list of tool_use and tool_result blocks and read them like a transcript. Nine times out of ten the bug is visible the moment you see what the model was looking at when it chose badly — a truncated result, a tool whose description overlaps another, a schema that allowed a nonsense value.

Failure mode one: loops that never terminate

Loops are the most expensive failure because the agent looks busy while making no progress. The classic pattern: the model calls a tool, gets an error or empty result, apologizes, and calls the same tool again with nearly identical arguments. Without a guard it will do this until it hits your turn cap, spending real tokens each cycle.

flowchart TD
  A["Agent turn"] --> B{"Same tool + args as last 2 turns?"}
  B -->|No| C["Execute tool"]
  B -->|Yes| D["Loop detected"]
  C --> E{"Result error or empty?"}
  E -->|No| F["Continue run"]
  E -->|Yes| G["Inject corrective hint"]
  G --> A
  D --> H["Halt & escalate to human"]
  F --> I{"Goal met?"}
  I -->|Yes| J["Finish"]
  I -->|No| A

The cleanest fix is a loop detector outside the model. Keep a rolling fingerprint of the last few tool calls — tool name plus a hash of the arguments — and if you see the same fingerprint repeat two or three times, break. Do not just kill the run; feed the model a pointed message: "You have called search_orders with these arguments twice and gotten zero results. The order ID may be wrong. Ask the user or try a different field." Claude responds well to being told why it is stuck, because it changes the visible context that drives the next decision.

Loops also come from missing stop conditions. If your system prompt says "keep working until the task is done" but never defines done, the model has no exit. Give it an explicit completion signal — a submit_result tool it must call, or a sentinel phrase your harness watches for — so termination is a deliberate action, not a guess.

Failure mode two: the wrong tool gets called

When an agent has fifteen tools, the model's job is partly retrieval: pick the right one from a menu. Wrong-tool errors almost always trace back to overlapping or vague tool descriptions. If get_customer and lookup_account both say "fetch customer information," the model has no principled way to choose, and it will guess differently across runs.

The fix is to write tool descriptions like API docs for a new hire who will never ask a follow-up question. State exactly when to use the tool, when not to, and what distinguishes it from its neighbors: "Use get_customer for billing identity by email. Do not use it for support tickets — use search_tickets for those." When you have many tools, consider grouping them behind an MCP server and trimming the active set per task, because a smaller, sharper menu produces sharper selection.

Debugging this is concrete: pull every run where the wrong tool fired and look at the description the model saw. If a human reading only those descriptions would also have been confused, the model is not the problem, your documentation is. Rewrite, then re-run the same inputs and confirm the selection flips.

Failure mode three: hallucinated arguments

The subtlest failure is when the model calls the right tool but invents a parameter — a customer ID it never saw, a date in the wrong format, a status enum that does not exist. The model is pattern-matching to a plausible-looking argument because your schema permitted it. A permissive schema is an invitation to hallucinate.

Tighten the JSON schema you give Claude for each tool. Use enum for closed sets so the model literally cannot emit an invalid status. Use pattern and format for IDs and dates. Mark fields required only when they truly are, and add a one-line description on each parameter explaining where its value should come from ("must be an order ID returned by a prior search_orders call — never fabricated"). Then validate again in code, because schema enforcement on the model side is best-effort, not a guarantee.

When you catch a hallucinated argument, do not silently fail. Return a structured error the model can act on: "order_id 'ORD-0000' was not found. Valid order IDs come from search_orders results." That closes the loop and teaches the model, within the run, to stop guessing.

Building a debug loop you can trust

Put these together into a harness that assumes nothing. Every tool result is validated before it re-enters the conversation. Every tool call is checked against a recent-call fingerprint for loops. Every argument is schema-validated and, where cheap, sanity-checked against state. And every run writes a replayable transcript so a failure becomes a regression test, not a mystery. With Claude's larger context windows you can afford to keep rich history, but resist dumping raw blobs — summarize tool results so the model reasons over signal, not noise.

One more practice pays off disproportionately: add a lightweight self-check turn for risky actions. Before a destructive or irreversible tool call, have the agent state in one sentence what it is about to do and why, which gives both the model and your logs a checkpoint. You can gate that sentence behind a confirmation tool for anything that writes or deletes.

Frequently asked questions

What is the fastest way to debug a failing Claude agent run?

Dump the full ordered message history — system prompt, tool definitions, every tool call with exact arguments, every tool result — and read it as a transcript. The bad decision is almost always explainable by what the model could see at that turn, such as a truncated result or two near-identical tool descriptions.

How do I stop an agent from looping forever?

Run a loop detector outside the model: fingerprint each tool call by name plus a hash of its arguments, and break if the same fingerprint repeats two or three times. On break, inject a specific corrective hint explaining why it is stuck and escalate to a human if needed. Also give the agent an explicit completion tool so "done" is a real action.

Why does Claude sometimes invent tool arguments?

Usually because the tool's JSON schema is too permissive, so a plausible-looking value passes. Constrain with enums, patterns, and required fields, describe where each value should come from, validate again in code, and return structured errors that tell the model the value was invalid rather than failing silently.

Should I fix the prompt or the tools first?

Fix tool definitions and schemas first. Wrong-tool and hallucinated-argument failures are overwhelmingly caused by vague descriptions and loose schemas, and those are deterministic to improve. Prompt tuning matters, but it is a weaker lever than giving the model a clean, unambiguous menu of well-specified tools.

From flaky runs to reliable agents

CallSphere runs these same debugging disciplines — loop detection, strict tool schemas, and replayable traces — on voice and chat agents that handle live customer calls, where a hallucinated argument is a real botched booking. See how reliable agentic AI sounds on a phone line 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.