Debugging Claude Legal Agents: Loops & Bad Tool Calls

The first time a Claude agent reviewed a stack of commercial leases for one of our pilot teams, it did something unnerving: it re-opened the same indemnification clause eleven times, each pass producing a slightly different summary, never converging on a citation. No exception was thrown. No tool errored. The run simply burned tokens until it hit the turn limit. If you are deploying Claude across the legal industry — contract review, intake triage, deposition prep, regulatory research — these are the failures you actually fight, and almost none of them look like a traditional crash.

Legal work amplifies agent failure modes because the documents are long, the stakes are high, and the tools (document stores, clause libraries, e-discovery indexes, matter-management systems) return dense, ambiguous results. A debugging discipline built for web apps does not transfer cleanly. You need to reason about what the model decided, not just what the code did.

The three failure modes that dominate legal agents

Across the deployments we have watched, agent misbehavior clusters into three patterns. The first is looping: the agent repeats a tool call or a reasoning step without making progress, usually because each result fails to satisfy an implicit success condition it can never meet. In legal review this shows up when the agent keeps searching a clause library for an exact phrase that simply is not in the contract.

The second is the wrong tool call: the agent reaches for search_caselaw when it should have called get_matter_documents, often because two tools have overlapping descriptions. The third is hallucinated arguments: the agent invents a matter_id or a docket number that looks plausible but does not exist, because the schema told it a string was required and it had no real value to supply.

A useful working definition: an agent failure mode is a repeatable, undesired pattern in an agent's decision loop that produces no error yet prevents the task from completing correctly. Naming the mode is half the fix, because each one has a different root cause and a different remedy.

Reading the trace, not the output

The single most valuable debugging habit is to stop reading the final answer and start reading the full message trace: every prompt, every tool call with its exact arguments, every tool result, and the model's text between calls. Claude Code and the Claude Agent SDK both expose this transcript. When you have it, the loop you could not explain becomes obvious — you can see the agent call the same tool with identical arguments three times and watch the result come back empty each time.

flowchart TD
  A["Agent run misbehaves"] --> B{"Did a tool error?"}
  B -->|Yes| C["Fix tool / schema / auth"]
  B -->|No| D{"Same call repeated?"}
  D -->|Yes| E["Loop: add progress check & stop condition"]
  D -->|No| F{"Wrong tool chosen?"}
  F -->|Yes| G["Disambiguate tool descriptions"]
  F -->|No| H{"Args invented?"}
  H -->|Yes| I["Tighten schema, require lookup first"]
  H -->|No| J["Inspect reasoning, refine system prompt"]

Instrument the trace before you ever ship. Log each tool call's name, arguments, latency, and a hash of the result. For legal agents, also log which document or clause the model claims to be citing, because hallucinated citations are the failure that actually gets a firm in trouble. When a partner asks "where did this come from," you want the answer in your logs, not in a guess.

Killing loops with explicit progress signals

Loops happen when the agent has no way to know it is stuck. The fix is to give it one. The cheapest intervention is a loop guard outside the model: track the last N tool calls, and if the same tool fires with the same arguments more than twice, inject a system message that says the call returned the same result and the agent must try a different approach or report that the information is unavailable.

The deeper fix is to make the success condition reachable. If your contract-review agent loops searching for a "termination for convenience" clause that isn't present, it is because nothing told it that absence is a valid finding. Add that to the prompt explicitly: "If a clause is not present after one search, record 'not found' and move on." Legal agents loop most often on negative facts, and negative facts need to be first-class outcomes, not error states.

Disambiguating tool calls and pinning arguments

Wrong-tool errors are usually a documentation problem, not a model problem. When two MCP tools have descriptions like "search documents" and "find documents," Claude has no principled way to choose. Rewrite descriptions to be mutually exclusive and to state when not to use the tool: "Use get_matter_documents only when you already have a matter_id; for free-text search across all matters, use search_documents." Tool descriptions are prompt engineering, and in legal deployments they are the highest-leverage prompt you will write.

Hallucinated arguments are best stopped at the schema. Make identifiers non-guessable: never let the model free-type a matter_id. Instead, expose a list_matters tool that returns valid IDs, and require that the model select one. If a parameter has an enumerable domain, encode it as an enum so the model physically cannot invent a value. When you must accept a free-form argument, validate it server-side and return a precise, instructive error — "matter_id 88213 not found; call list_matters to see valid IDs" — so the agent can self-correct on the next turn instead of looping.

Reproducing failures deterministically

Legal-agent bugs are maddening because they are intermittent. The same lease passes review on Monday and loops on Wednesday. To make them reproducible, freeze the inputs: capture the exact document set, the tool definitions, and a fixed seed for any sampling you control, then replay. Lower the temperature toward zero while debugging so the model's choices stop drifting. Once you can reproduce the loop or the wrong call on demand, you can bisect — remove tools one at a time, simplify the document, shorten the prompt — until the trigger is isolated.

Keep a regression library of these captured failures. Every time a legal agent misbehaves on a real matter, scrub the privileged content, reduce it to the minimal triggering case, and add it to your test suite. Over a few months this library becomes the most honest description of your agent's weaknesses you will ever own.

Frequently asked questions

Why does my Claude legal agent loop instead of finishing?

Almost always because a success condition is unreachable — it is hunting for a clause or value that does not exist, with no instruction that "not found" is a valid result. Add explicit negative-outcome handling and an external loop guard that breaks after repeated identical calls.

How do I stop the agent from inventing matter IDs or docket numbers?

Don't let it type them. Expose lookup tools that return valid identifiers, use enums where the domain is fixed, and validate every argument server-side with an instructive error so the agent can recover on the next turn rather than fabricate.

What is the fastest way to debug a misbehaving agent?

Read the full message trace, not the final output. Seeing every tool call, its exact arguments, and each result usually makes the failure mode — loop, wrong tool, or hallucinated argument — visible within a minute.

Should I lower temperature for legal agents?

For debugging, yes — near-zero temperature makes runs reproducible. In production, a low but non-zero temperature is common; the more important controls are tight tool schemas, clear descriptions, and validated arguments rather than temperature alone.

Bringing reliable agents to your phone lines

CallSphere takes these same debugging disciplines — trace inspection, loop guards, and tight tool schemas — and applies them to voice and chat agents that answer every call, pull from your systems mid-conversation, 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.