The evaluation guide earlier in this series covered measuring whether an agent works. This one is about what to actually do when it doesn't - the handful of failure patterns that show up again and again across different agents and frameworks, and where to look first for each one.
Hallucinated tool calls
A model can request a tool call with a name that doesn't exist, or with arguments that don't match the tool's actual schema - it's generating a plausible-looking call, not one it's verified is real. This usually traces back to a tool menu that's too large or too similar-sounding (several tools with overlapping names or purposes), or a tool description vague enough that the model guesses at the interface rather than reading it precisely. The fix is almost always narrower, more distinctly named tools with precise schemas, not a bigger warning in the system prompt telling the model to "only use real tools."
Infinite or unproductive loops
An agent that keeps calling the same tool with slightly different arguments, or bounces between two tools without making progress, is usually stuck because an earlier observation was ambiguous or unhelpful and the model doesn't have a good strategy for recognizing that. Beyond the hard iteration ceiling covered in the agent loop guide - which stops the bleeding but doesn't fix the cause - the actual fix is often improving what a tool returns on a bad or empty result: a clear "no results found for X" is much easier for a model to reason about than an empty array or a cryptic error code.
Debugging an agent means finding the specific step where reasoning went wrong, not just noticing the final answer was bad.
Tool misuse: the right tool, wrong way
Distinct from hallucinating a call entirely, this is the model calling a real, correctly-named tool but with arguments that technically satisfy the schema while missing the actual intent - searching for the wrong term, passing a date range that doesn't match what the user asked for. This is harder to catch automatically than a malformed call, because nothing errors; it just quietly produces a wrong result. Realistic test prompts (covered in the evaluation guide) that check the actual arguments a tool was called with, not just whether a tool was called, are what surface this.
Context poisoning
An error or a piece of bad information that enters the context early in a run - a failed tool call, a misread instruction, a hallucinated fact - doesn't just disappear; it stays in context and can influence every subsequent planning step, sometimes compounding into an answer that's confidently wrong in a way that's hard to trace back to its origin. This is why inspecting the full trace, not just the final answer, matters: the actual root cause is often several steps earlier than where the failure became visible.
A practical debugging checklist
When an agent produces a wrong result: reproduce it with the same inputs, pull the full trace rather than just the output, walk forward step by step until you find the first point where behavior diverges from what you'd expect, and fix that specific step - a tool description, a schema, a piece of missing context - rather than adding a general instruction to the system prompt telling the model to "be more careful," which rarely holds up on the next unusual input.