Debugging Claude agents: loops, bad tool calls, fixes (Extending Claude Skills MCP)

The first time an agent gets stuck, it rarely fails loudly. It just keeps going. Claude calls a search tool, reads the result, decides the result wasn't quite right, calls the same tool again with a barely different query, and twenty turns later you are staring at a transcript that burned thousands of tokens and produced nothing. When you extend Claude with Agent Skills and Model Context Protocol (MCP) servers, you add real power and a new surface area for failure. Debugging that surface is a distinct engineering skill, and it has its own vocabulary of symptoms.

This post is a practical guide to the failure modes you will actually hit — tool-call loops, wrong tool selection, and hallucinated arguments — and how to diagnose and fix each one. The goal is not to make the agent never fail; it is to make failures legible, bounded, and cheap to recover from.

Why agentic failures are different from prompt failures

A single completion either answers your question or it doesn't, and you can read it in one glance. An agentic run is a loop: Claude reasons, picks a tool exposed by an MCP server, the server executes, the result comes back, and the loop repeats until a stop condition. Failures hide inside that loop. The final answer might look fine while three wasted tool calls sit upstream, or the answer might be confidently wrong because one tool returned an error string that Claude treated as data.

The most important debugging move, before any fix, is to make the loop observable. Log every turn as a structured record: the model's stated intent, the exact tool name, the full arguments object, the raw server response, and the token count for that turn. Without that trace you are guessing. With it, most bugs become obvious within two or three transcripts.

A useful definition to anchor on: a tool-call loop is a failure mode in which an agent repeatedly invokes the same or near-identical tool calls without making progress toward its goal, usually because the result it gets back never satisfies its internal stop condition. Naming the pattern is half the battle, because each named pattern has a known set of causes.

The three failure modes you will hit most

Loops. Claude calls a tool, is unsatisfied, and calls again. The cause is almost always ambiguity: the task has no crisp definition of done, the tool returns low-signal output, or the result format is hard to interpret. Loops also appear when an MCP server returns an error as a 200-status string instead of a real error, so Claude thinks it should retry rather than stop.

Wrong tool calls. The agent picks list_files when it needed search_files, or calls a write tool when read-only was intended. This is a selection problem, and it traces back to tool descriptions. If two MCP tools have overlapping or vague descriptions, Claude has no reliable basis to choose. The fix lives in the server's tool metadata, not the prompt.

Hallucinated arguments. Claude calls a real tool with a fabricated argument — an invented record ID, a date format the API rejects, a required field left out. This happens when the JSON schema for the tool's input is loose, when examples are missing, or when the agent is reasoning about data it never actually fetched.

flowchart TD
  A["Agent run produces bad output"] --> B{"Same tool called 3+ times?"}
  B -->|Yes| C["Loop: add stop condition & dedupe guard"]
  B -->|No| D{"Right tool for the step?"}
  D -->|No| E["Selection bug: tighten tool descriptions"]
  D -->|Yes| F{"Args valid vs schema?"}
  F -->|No| G["Hallucinated args: tighten schema & add examples"]
  F -->|Yes| H["Inspect raw server response for silent errors"]

Killing loops with stop conditions and dedupe guards

The cheapest loop fix is a hard cap on turns and on repeated calls. In the Claude Agent SDK you can track a fingerprint of each tool call — the tool name plus a hash of its arguments — and refuse or warn when the same fingerprint repeats. When Claude sees a message like "you already called search with this exact query and it returned no results; try a different approach or stop," it usually breaks out of the cycle on its own.

Equally important is giving the task a definition of done that Claude can check. "Find the customer record" is open-ended; "find the customer record and return its ID, or report that no record exists" gives the agent a terminal state. Many loops are simply an agent that doesn't know it is allowed to give up. Make giving up an explicit, acceptable outcome.

Finally, audit your MCP servers for silent errors. A server that returns {"result": "Error: rate limited"} with a success status invites retries. Return real error semantics — a distinct error field or an MCP error response — so Claude can distinguish "try again" from "this will never work."

Fixing wrong tool selection at the source

Tool descriptions are prompt engineering, even though they live in your server code. Each MCP tool description should state what the tool does, when to use it, when not to use it, and what it returns. If you have a search_orders and a get_order, say plainly that search is for discovery by criteria and get is for fetching one known ID. Overlap is the enemy; disambiguate explicitly.

When an agent has access to dozens of tools, selection accuracy degrades simply from volume. Scope the toolset per task. A skill that handles refunds doesn't need the analytics tools in context. Loading only the relevant Skills and MCP tools for the current job both reduces wrong selections and saves tokens. If you can't reduce the toolset, group tools and add a routing step where Claude first picks a category, then a specific tool.

Stopping hallucinated arguments

Hallucinated arguments are a schema and grounding problem. Tighten the JSON schema: mark required fields required, constrain enums, give format hints, and add a one-line description to every parameter with an example value. Claude follows a schema far more reliably than it follows prose, so push your constraints into the schema where the model can't miss them.

The deeper fix is grounding. An agent hallucinates an ID because it never fetched a real one. Structure workflows so that any identifier used in a write must have come from a prior read in the same run. If you see a write tool called with an ID that appears nowhere in earlier tool results, that is your bug — and a validation guard that rejects unknown IDs at the server turns a silent data-corruption risk into a clean, recoverable error.

Building a debugging workflow you can repeat

Treat every production incident as a saved transcript. Keep a small library of failing runs and replay them against changes to skills, schemas, and descriptions. Because agent behavior is non-deterministic, run each replay several times and look at the distribution, not a single pass. A fix that works once and fails twice is not a fix.

Wire structured logging into the agent loop so that, for any run, you can answer four questions instantly: what did Claude intend, which tool did it call, what arguments did it pass, and what came back. Most teams that struggle with agent debugging are missing one of those four. Once you can see all four for every turn, the loops, wrong calls, and hallucinated args stop being mysterious and start being ordinary bugs you fix in an afternoon.

Frequently asked questions

How do I tell a loop from legitimate retries?

Fingerprint each tool call by name plus an argument hash. Legitimate retries vary their arguments toward a goal; a loop repeats the same fingerprint or oscillates between two with no new information entering the run. If three identical fingerprints appear, treat it as a loop and inject a stop signal.

Should I fix tool-selection bugs in the prompt or the MCP server?

Fix them in the MCP server's tool descriptions and schemas first. Those travel with the tool to every agent and every run, while a system-prompt patch is fragile and easy to forget. Reserve prompt-level guidance for genuinely task-specific routing.

What's the fastest way to catch hallucinated arguments?

Validate at the server boundary against a strict schema and reject unknown identifiers that never appeared in prior tool results within the same run. This converts a silent bad write into an explicit, logged error that Claude can read and recover from on the next turn.

How many times should I replay a fix before trusting it?

Run the failing transcript at least five to ten times and look at the success rate, because agent runs are non-deterministic. A single green pass tells you almost nothing; a stable rate across replays tells you the fix actually changed behavior.

From flaky agents to dependable phone lines

The same discipline — observable loops, tight tool contracts, grounded arguments — is what keeps a real-time voice agent reliable when a customer is on the line. CallSphere brings these agentic patterns to voice and chat, with assistants that call tools mid-conversation and recover gracefully from failure. 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.