Debugging Claude Code Agents: Loops and Bad Tool Calls

When people ask why Claude tops coding benchmarks, the honest answer is partly about the model and partly about the harness around it. A strong model still produces broken runs if the agent loop, tool definitions, and observability are sloppy. The frustrating part is that agentic failures rarely look like a clean stack trace. Instead you get a run that almost worked: Claude edited the right file, ran the test, misread the output, and then spent eleven turns re-editing the same three lines. Debugging that is a different skill than debugging code, and most teams learn it the hard way.

This post is about the three failure modes that eat the most engineering hours when you build on Claude Code or the Claude Agent SDK: infinite or near-infinite loops, calls to the wrong tool, and hallucinated arguments. For each one I will show how to spot it in a transcript, what usually causes it at the harness level, and the specific change that makes it stop happening.

Key takeaways

• Most agent loops come from a missing or unobservable stop condition, not from the model being "confused" — give Claude a verifiable signal that the task is done.
• Wrong-tool calls usually trace back to two tools whose descriptions overlap; tightening one description fixes the ambiguity faster than any prompt tweak.
• Hallucinated arguments drop sharply when tool schemas are strict (enums, required fields) and your executor returns a usable error instead of throwing.
• The single highest-leverage debugging artifact is a complete, replayable transcript of every message, tool call, and tool result.
• Add a turn budget and a loop detector early; they convert silent runaway runs into a clear, actionable failure.

Why agentic debugging is different

In a normal program, a bug is deterministic: the same input gives the same wrong output, and you can bisect it. An agent run is a sequence of model decisions, each conditioned on the growing transcript, and each shaped by sampling. The same prompt can succeed on Monday and loop on Tuesday. That non-determinism is what makes people throw up their hands. The fix is not to chase the one bad token — it is to treat the transcript as your primary debugging surface and look for structural causes.

A useful definition to anchor on: an agent failure mode is a recurring, classifiable way a tool-using model deviates from the intended trajectory — distinct from a one-off wrong answer because it reproduces across runs once the conditions are present. When you frame it that way, debugging becomes pattern recognition. You read ten failed transcripts, you notice the same shape, and you fix the condition that produces the shape rather than the individual run.

The practical implication: invest in transcript capture before you invest in clever prompts. If you cannot replay a failed run turn by turn — system prompt, every tool definition, every tool call with its exact arguments, every tool result Claude saw — you are debugging blind. Everything below assumes you have that.

Failure mode one: loops

A loop is when Claude repeats the same action, or a small cycle of actions, without making progress. The classic version: edit a file, run the test, see a failure, edit the file back toward the previous state, run the test, repeat. Sometimes it is subtler — Claude reads the same three files every turn because it never wrote down what it learned, so each turn starts fresh.

The root cause is almost always a missing or invisible stop condition. Claude does not know it is done because nothing in the transcript clearly says so. If the only signal is "tests pass," but the test command's output is buried in 4,000 lines of build log, Claude may genuinely not see the pass. The flow below shows where a healthy loop diverges from a stuck one.

flowchart TD
  A["Claude picks next action"] --> B["Execute tool call"]
  B --> C{"Progress signal visible?"}
  C -->|Yes, task done| D["Stop and report"]
  C -->|Yes, more to do| A
  C -->|No clear signal| E{"Same action as last 2 turns?"}
  E -->|No| A
  E -->|Yes| F["Loop detector trips"]
  F --> G["Inject hint or abort with diagnostics"]

Three fixes, in order of leverage. First, make the success signal explicit and small: run the test and pipe it through a script that prints only PASS or the failing assertion, so the result Claude sees is unambiguous. Second, add a cheap loop detector in your harness — hash the last few tool calls and arguments, and if the same hash repeats, break the loop and inject a message like "You have tried this edit twice with the same result; investigate why the test fails before editing again." Third, set a turn budget so a runaway run aborts with a diagnostic instead of burning tokens silently.

Failure mode two: wrong tool calls

Here Claude calls a real tool, with plausible arguments, but it is the wrong tool for the job — using read_file to search a directory it should have greped, or calling a generic http_request tool when you exposed a purpose-built create_ticket tool. The output often looks fine for a turn or two, then the run drifts off course.

The cause is overlapping tool descriptions. Claude routes to a tool based mostly on its name and description, so if two tools sound like they do similar things, it will sometimes pick the broader, more flexible one. The fix is to write tool descriptions that state not just what the tool does but when to use it and when not to. A good description includes a negative clause: "Use this to fetch a single known file by path. Do not use it to search; use search_code for that."

Below is a tool definition shaped the way Claude routes well against. Note the explicit boundary in the description and the strict schema — both reduce mis-routing.

{
  "name": "search_code",
  "description": "Search the repository for a string or regex across files. Use this whenever you need to FIND where something is defined or used. Do NOT use read_file to scan directories — use this instead.",
  "input_schema": {
    "type": "object",
    "properties": {
      "pattern": { "type": "string", "description": "Regex or literal string to search for" },
      "path": { "type": "string", "description": "Directory to scope the search; defaults to repo root" }
    },
    "required": ["pattern"]
  }
}

When you still see mis-routing after tightening descriptions, the answer is usually to remove a tool, not add prompt text. Every redundant tool is a chance to route wrong. If two tools do nearly the same thing, merge them or delete the one you do not need. Claude routes better against a small, sharp toolset than a large, fuzzy one.

Failure mode three: hallucinated arguments

This is the one that looks scariest and is often the easiest to engineer away. Claude calls the right tool but invents an argument: a file path that does not exist, a customer ID it never saw, a parameter your API does not accept. Left unguarded, the tool executes against garbage and the run goes sideways.

Two mechanisms fix the bulk of it. First, make schemas strict. Use enums for fields with a fixed set of values, mark required fields, and constrain formats. Claude is far less likely to invent a status of "pending_review" if the schema declares the field as an enum of the three valid values. Second — and this is the part teams skip — make your executor forgiving. When Claude passes a bad argument, do not throw a raw exception; return a structured error that tells it what was wrong and what valid values look like.

// Bad: opaque failure Claude cannot recover from
throw new Error("invalid id");

// Good: actionable result Claude can self-correct on
return {
  error: "No customer with id 'C-9999'. Use search_customers first to get a valid id.",
  hint: "Valid ids look like 'C-' followed by 5 digits."
};

That error message becomes the next tool result Claude reads, and a well-written one routinely produces a clean recovery on the following turn. The model is good at fixing its own mistakes when it is told, in plain language, what the mistake was.

Common pitfalls

• Debugging without a transcript. If you only log final outputs, you cannot see the turn where things went wrong. Capture every message and tool result, and make runs replayable.
• Patching with more system prompt. Each "don't do X" line you add dilutes the rest. Prefer fixing the tool schema, the description, or the executor's error output over growing the prompt.
• Throwing exceptions from tools. A raw stack trace as a tool result teaches Claude nothing. Return structured, instructive errors so the model can recover.
• No turn budget. Without a cap, a single looping run can quietly cost more than a day of normal usage. Cap turns and abort with diagnostics.
• Burying success signals. If "done" is hidden in noisy output, Claude may not see it and will loop. Filter tool output down to the signal that matters.

Debug a stuck run in five steps

1. Pull the full transcript of the failed run and read it turn by turn until you find the first turn that went off the rails.
2. Classify the failure: loop, wrong tool, or hallucinated argument. The shape of the transcript tells you which.
3. For a loop, add or surface a clear success signal and a loop detector; for a wrong tool, tighten or merge the overlapping tool descriptions; for a bad argument, harden the schema and return an instructive executor error.
4. Replay the same transcript against the fix to confirm the off-the-rails turn now goes the right way.
5. Add the failed transcript to a small regression set so the same failure mode is caught automatically next time.

Quick reference: failure mode to first fix

Frequently asked questions

How do I tell a loop from slow-but-correct progress?

Hash each tool call with its arguments and compare across turns. Genuine progress changes the arguments — different files, different patches. A loop repeats the same or nearly-same call. If the last three calls hash identically, you have a loop, not slow progress.

Should I lower temperature to reduce hallucinated arguments?

It can help marginally, but it is not the lever that matters. Strict schemas and instructive executor errors do far more, and they help on every run regardless of sampling. Fix the tool contract first; treat temperature as a minor tuning knob.

Does using a more capable model like Opus remove these failure modes?

A stronger model loops less and mis-routes less, but the same structural causes still bite under a weak harness. Better tool definitions, clear success signals, and good error feedback help every model in the Claude family, so build those regardless of which one you run.

What is the single most valuable thing to log?

The complete, ordered transcript: system prompt, each tool definition, each tool call with exact arguments, and each tool result as Claude saw it. With that you can replay and diagnose any failure; without it you are guessing.

Bringing agentic AI to your phone lines

The same debugging discipline — clear stop conditions, sharp tool definitions, recoverable errors — is what keeps a live voice agent on track mid-call. CallSphere builds these patterns into voice and chat assistants that answer every call, use tools in real time, and book work around the clock. 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.