Debugging Claude Code Agents: Fixing Loops & Bad Tool Calls

At a recent Built-with-Opus hackathon, the teams that shipped working agents had one thing in common: they spent more time reading transcripts than writing prompts. When a Claude Code agent goes wrong, it rarely crashes loudly. Instead it quietly drifts — re-reading the same file four times, calling a tool with a path that does not exist, or inventing a function argument it was never told about. By the end of the weekend, the pattern was obvious. The hard part of agent engineering is not getting Claude to act. It is debugging what it does when nobody is watching the loop tick by.

This post collects the failure modes we saw over and over on Opus 4.8 runs, and the concrete moves that fixed them. The examples are drawn from real hackathon projects — a repo-refactoring agent, a data-pull agent, and a deploy assistant — but the diagnostic playbook applies to anything built on Claude Code or the Claude Agent SDK.

Why agent bugs hide instead of crashing

A traditional program fails at a stack frame. An agent fails across a conversation. The model emits a tool call, the harness runs it, the result comes back, and Claude decides what to do next. A bug can live in any of those four steps, and the symptom you observe — "it never finished" — is several turns downstream of the cause. That gap between cause and symptom is why agent debugging feels unfamiliar even to strong engineers.

The fix is to treat the transcript as your primary log. Every Claude Code run produces a turn-by-turn record of reasoning text, tool calls with their exact arguments, and tool results. Read it like a flight recorder. Nine times out of ten the bug announces itself: a tool result that says "file not found" three turns before the model gives up, or a reasoning block where Claude convinces itself a field exists. If you only look at the final answer, you are debugging blind.

The three failure modes that ate the most time

Across the hackathon, three classes of failure dominated. The first is the loop: Claude repeats a near-identical action because each attempt returns the same unhelpful result and nothing in context tells it to change strategy. The second is the wrong tool call: the right intent, the wrong tool — using a broad search when a direct read was available, or writing a file before reading it. The third is the hallucinated argument: Claude calls a real tool with a plausible-but-fictional parameter, like a config key it assumed from naming conventions rather than from the schema.

flowchart TD
  A["Agent run starts"] --> B{"Same tool call repeated >2x?"}
  B -->|Yes| C["Loop: inject result diff or hard step cap"]
  B -->|No| D{"Tool result = error?"}
  D -->|Yes| E{"Bad arg or wrong tool?"}
  E -->|Bad arg| F["Hallucination: tighten schema & examples"]
  E -->|Wrong tool| G["Mis-route: sharpen tool descriptions"]
  D -->|No| H["Run healthy: log & continue"]

The diagram above is the triage flow our teams converged on. When a run misbehaves, you walk it top to bottom: first ask whether an action is repeating, then whether tool results are erroring, then classify the error as a bad argument versus a wrong tool. Each branch has a different fix, and mixing them up wastes the most time. People tried to solve loops by rewording the system prompt when the real issue was a tool returning an ambiguous empty result.

Killing loops without lobotomizing the agent

The naive loop fix is a hard step cap, and you should absolutely have one as a backstop. But a cap only stops the bleeding; it does not cure the disease. The loops we saw were almost always driven by uninformative tool results. An agent searches for a symbol, gets an empty array, searches again with a slightly different query, gets an empty array, and so on. The result never tells Claude why it is empty, so the model keeps guessing.

The durable fix is to make tool results self-explanatory. Instead of returning [], return {"matches": [], "searched": "src/**", "hint": "no symbol named X; did you mean Y?"}. That single change broke most loops outright, because now the next turn has new information to act on. We also added a lightweight loop detector in the harness: if the last two tool calls were byte-identical, inject a system note saying "This exact call was already made and returned the same result; change approach." Claude on Opus 4.8 responds well to that nudge because it has the reasoning headroom to reconsider strategy rather than repeat.

Wrong tool calls are usually a description problem

When Claude reaches for the wrong tool, engineers instinctively blame the model. In practice the tool descriptions were vague. If two tools both mention "get data" in their description, the model has to guess which one applies, and it will guess wrong under ambiguity. The hackathon teams that had clean routing had written tool descriptions that stated when to use this and when not to — not just what the tool does.

A good description reads like a decision rule: "Use read_file when you know the exact path. Do NOT use search_code for this — that is for discovery when the path is unknown." Negative guidance matters as much as positive. We also found ordering helped: list the most specific, cheapest tools first, because the model tends to anchor on early options. After tightening descriptions on the refactor agent, wrong-tool calls dropped to near zero without any change to the underlying prompt.

Hallucinated arguments and how schemas stop them

Hallucinated arguments are the scariest failure because they look correct. Claude calls a real tool, the JSON is well-formed, and the parameter name is exactly what you would have named it — it just does not exist. The model filled a gap with a confident guess. This happens most when a tool's input schema is loose: a free-form object, an optional field with no description, or an enum documented only in prose.

Two defenses worked. First, make the schema strict and self-documenting. Use enums with the exact allowed values, mark required fields, and put a one-line description on every parameter that says what valid input looks like. When the schema is tight, the harness rejects the bad call before it executes, and the error message goes straight back to Claude, which corrects on the next turn. Second, give one or two concrete invocation examples in the tool description. Models pattern-match hard on examples; a single correct sample call suppresses a lot of inventive nonsense.

Building a transcript-first debugging habit

The meta-lesson from the weekend: instrument first, prompt second. Before tuning any wording, make sure you can answer three questions from logs alone — which tool was called, with what exact arguments, and what came back. If your harness does not surface those, fix that before anything else. Teams that had clean structured logs debugged in minutes; teams that printed only final outputs spent hours guessing.

Add a few cheap guards to the harness itself: a global step cap, a duplicate-call detector, schema validation on every tool, and a rule that any tool error is echoed verbatim into context so Claude can react. These are not model features; they are engineering hygiene around the model. With them in place, Opus 4.8's reasoning does the rest — it is genuinely good at recovering from a clear error message, and genuinely bad at recovering from silence.

Frequently asked questions

What is an agent loop in Claude Code?

An agent loop is a failure mode where a Claude Code agent repeatedly issues the same or nearly identical tool call because each result is uninformative and nothing in context signals a need to change strategy. The standard fixes are a hard step cap as a backstop, plus making tool results self-explanatory so the model gains new information each turn.

How do I stop Claude from hallucinating tool arguments?

Tighten the tool's input schema so invalid arguments are rejected before execution, use enums with exact allowed values, add a one-line description to every parameter, and include one concrete example invocation in the tool description. Strict schemas turn a silent hallucination into a fast, correctable error.

Why does my agent pick the wrong tool?

Almost always because tool descriptions overlap or are vague. Rewrite each description as a decision rule that states when to use the tool and when not to, include negative guidance, and order tools from most specific to most general. Clear routing rules eliminate most mis-selection without touching the system prompt.

What is the fastest way to debug an agent run?

Read the transcript turn by turn as a flight recorder. Find the first tool result that errored or returned ambiguously, and trace forward to where the agent went off course. The cause is usually several turns upstream of the visible symptom, so end-of-run output alone will mislead you.

Bringing agentic AI to your phone lines

The same debugging discipline — strict tool schemas, self-explaining results, and transcript-first triage — is exactly what keeps a live voice agent reliable. CallSphere applies these agentic-AI patterns to voice and chat, with assistants that answer every call, use tools mid-conversation, and recover gracefully when something goes wrong. 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.