AI engineeringagentstoolsdebuggingUpdated June 2026
Diagnose why an agent is misusing, ignoring, or fumbling its tools.
Why it works: Requiring the actual transcript stops the model from theorizing; finding the exact decision point localizes the bug.
This is a message template. Fill in the blanks below, then paste it into the chat.
My agent is misbehaving with its tools. Help me diagnose why.
What the agent is supposed to do: [the task and workflow]
Tools it has: [list tools with one-line descriptions; paste the actual tool definitions if possible]
The misbehavior: [e.g. “calls the wrong tool”, “ignores a tool that’s clearly needed”, “calls tools in a loop”, “fabricates tool output instead of calling”]
A concrete failing example: [paste the actual transcript or trace: the agent’s reasoning and tool calls, not a summary]
Work through it systematically:
Tool definitions: are the names and descriptions actually telling the model when to use each one? Flag ambiguity or overlap between tools
The decision point: in the failing transcript, identify the exact moment the agent went wrong and what information it had at that point
Hypotheses ranked: most likely causes (prompt, tool schema, missing context, task framing) with how to test each one cheaply
The fix: concrete changes to try, starting with the cheapest