To debug an AI agent tool error, read the run trace to find the earliest step that failed, identify which class of error it is, reproduce that single tool call in isolation, then fix it at the layer where the fault actually lives: the prompt, the tool schema, the credentials, or a retry and fallback path. The mistake most people make is debugging the agent's final answer instead of the trace, which hides the real failing step several actions upstream.
This guide walks through that sequence end to end. It assumes you have access to the agent's run trace and logs, which is the single most important thing to have when something breaks. If you cannot see what tool the agent called, with what parameters, and what came back, you are guessing. Everything below starts from the trace.
The fast path to a fix
When an agent run produces a wrong or empty result, the temptation is to reword the user request and try again. Sometimes that works by accident, but it does not tell you what broke, so the same failure returns on the next variation. A reliable debugging loop has five steps, and they are worth doing in order:
- Find the failing step in the trace. Locate the first tool call that returned an error or an unexpected result, not the symptom at the end of the run.
- Classify the error. Auth, timeout, malformed parameters, schema mismatch, empty result, or rate limit. The class tells you where to look.
- Reproduce it by replaying that one tool call with the same inputs, outside the full agent loop.
- Fix it at the right layer. Prompt, schema, credentials, or retry and fallback, depending on what the class told you.
- Prevent recurrence with validation, a guard, and a regression case so the fix sticks.
The rest of this guide expands each step. The throughline is that tool use is where agents most often fail, because that is the boundary where the model's reasoning meets a real external system that has its own rules, formats, and failure modes.
Read the trace to find the failing step
A run trace is the ordered record of everything the agent did: each reasoning step, each tool call with its input parameters, and each tool response. Reading it well is the core debugging skill. The most common reading mistake is starting at the bottom, where the wrong final answer is, and working from there. The final answer is a symptom. The fault is usually several steps earlier, where a tool call quietly failed and the agent carried on with bad or missing data.
Read the trace top to bottom and ask three questions at each tool call:
- Did the call succeed? Look at the response status. An error response is the obvious case. A success status with an empty or unexpected body is the sneaky case that the agent often mishandles.
- Were the parameters correct? Compare what the agent sent against what the tool actually expects. A date in the wrong format, a missing required field, or an ID that does not exist will all surface here.
- Did the agent use the response correctly? Sometimes the tool worked and the agent misread the result. That is a reasoning problem, not a tool problem, and it points back to the prompt.
The first call where the answer to any of these is wrong is your failing step. Everything after it in the trace is consequence, not cause. If your traces are thin or missing, that is the first thing to fix; durable, queryable traces are the foundation of agent monitoring and observability, and without them every debugging session is slower than it needs to be.
The six common tool-error classes
Almost every tool failure falls into one of six classes. Naming the class is valuable because each one points to a specific layer to fix, which saves you from poking at the prompt when the real problem is a stale token.
Authentication and credential errors
The call is rejected before it runs because the credential is missing, expired, or lacks the right scope. In the trace this shows up as a 401 or 403 response, or a message about an invalid or expired token. The fix is never in the prompt. It is in the connection: refresh the token, reauthorize the integration, or grant the missing scope. If the credential expired mid-run, the same call will succeed once the connection is renewed, with no other change.
Timeouts
The tool accepted the call but took too long to respond and the agent gave up waiting. The trace shows a timeout or a deadline-exceeded message rather than a real response body. Timeouts are often transient, caused by a slow upstream service or a heavy query. The right fix is usually a retry with backoff rather than a code change, paired with a sensible timeout ceiling. If a tool reliably times out, the query itself may be too expensive and needs to be narrowed.
Malformed parameters
The call reached the tool, but a parameter was in the wrong format or shape: a date as text where an ISO string was expected, a number sent as a string, a missing required field, or an enum value the API does not accept. This is one of the most common classes because the agent constructs parameters from natural language and can guess wrong. The fix is usually clearer schema descriptions plus input validation that rejects bad values before the call goes out.
Schema mismatch
The tool definition the agent sees does not match what the underlying API actually accepts. The agent followed the schema faithfully, but the schema is wrong: a renamed field, a parameter the API now requires, or a type that changed. This class is easy to confuse with malformed parameters, and the trace tells them apart. If the agent sent exactly what the schema described and the API still rejected it, the schema is the fault, not the agent. Fix the tool definition.
Empty or unexpected results
The call succeeded with a clean status, but returned nothing useful: an empty list, a null field, or a shape the agent did not anticipate. The agent then either invents a plausible-looking answer or fails further downstream. This is the most dangerous class because nothing looks broken in the status code. Handle it by teaching the agent what an empty result means in your context and what to do about it, often through a clearer prompt instruction or a guard that catches the empty case.
Rate limits
The service rejected the call because too many requests arrived in a short window. The trace shows a 429 response or a quota message. This appears most often in loops, where the agent calls the same tool many times in quick succession. The fix is throttling and retry with backoff, and sometimes a structural change so the agent batches work instead of hammering the endpoint once per item.
Two of these classes, timeouts and rate limits, are transient by nature and respond well to fallback and retry strategies. The other four are deterministic and need a real fix at the prompt, schema, or credential layer.
Reproduce the failure in isolation
Once you know the failing step and its likely class, reproduce it before you change anything. Reproduction separates a real, fixable fault from a one-off transient blip, and it tells you whether the problem is in the tool or in how the agent called it.
Capture three things from the failed run: the original user request, the exact tool name, and the exact parameters the agent sent. Then replay that single tool call on its own, with those same parameters, outside the full agent loop. Two outcomes are possible, and each points somewhere different:
- It fails the same way in isolation. You have a deterministic reproduction. The fault is in the tool, the schema, or the credentials, and you can fix it directly and confirm the fix against the same replay.
- It succeeds in isolation. The tool is fine; the agent built the call wrong, or the failure was a transient timeout or rate limit. This points you back to the prompt, the schema description, or a retry policy rather than the tool itself.
Isolated reproduction is also how you avoid the classic trap of "fixing" something that was never broken. If you reword the prompt and the run happens to pass, you have learned nothing about whether you fixed the fault or just got a different sample. A clean reproduction gives you a pass or fail signal you can trust.
Fix it at the right layer
The single most important judgment in debugging an agent is choosing the layer to fix. The same visible symptom can come from four very different places, and patching the wrong layer either fails again immediately or papers over the problem until the next variation. Map the error class to the layer:
- Prompt layer. Fix here when the tool and schema are correct but the agent chose the wrong value, the wrong tool, or misread a result. Tighten the instruction, give an example of a correct call, or state what to do with an empty result. This is the right fix for reasoning errors, not for credential or schema faults.
- Schema layer. Fix here when the agent followed the tool definition and the API still rejected the call. Correct the field names, types, required flags, and descriptions so the definition matches the real API. A good description prevents malformed-parameter errors before they happen.
- Credentials layer. Fix here for any auth or scope failure. Refresh or reauthorize the connection and grant the needed scope. No amount of prompt engineering fixes an expired token.
- Retry and fallback layer. Fix here for transient timeouts and rate limits, and as a safety net for tools that can be unavailable. Add retry with backoff, and a fallback action or alternate tool when the primary keeps failing.
A useful test: if your fix would stop working the moment the user phrases the request slightly differently, you probably fixed the wrong layer. A schema or credential fix holds across phrasings; a prompt patch that hard-codes one case does not. When a failed tool call could leave a partial change behind, the layer question extends into error handling and rollback, so the agent can undo half-finished work rather than leaving a system in a broken state. And whenever you grant an agent the ability to retry or fall back to another tool, keep it inside your safety guardrails so a retry loop cannot run unbounded or take an action you did not intend.
Prevent the error from recurring
A fix that only addresses the single failed run is half a fix. The goal is that this class of error does not silently come back. After the immediate repair, add a guard at the layer that failed:
- Validate inputs before the call goes out. Reject a malformed parameter at the boundary with a clear message rather than sending it to the API and parsing a vague rejection. This is the cheapest defense against the most common class.
- Wrap transient calls in retry with backoff so a single slow response or a brief rate-limit spike resolves itself without a failed run.
- Add a fallback path for tools that can be unavailable, so the agent has a defined alternative instead of inventing an answer. When you give an agent access to multiple tools, a fallback can be a second tool that does the same job, and fallback chains let you order those alternatives.
- Keep a regression set. Add the exact failing inputs to a small list of cases you replay after any change to the prompt, schema, or tools. This is how you catch a fix that a later edit quietly undid.
Prevention also depends on seeing failures early. Good monitoring surfaces a rising error rate on a tool before a user reports a broken run, and the trace shows you the failing step the moment you open it. Errors that touch a connected system, such as a database the agent writes to, deserve the most careful guarding because a bad call there can change real data, not just return a wrong answer.
How Gravity handles tool errors
Gravity is an AI agent platform. The agents that run on it are built and maintained for Gravity by people who handle exactly this kind of debugging, so you do not have to. When you describe a task in plain words and an agent runs it, the platform records the run trace, classifies tool failures, and applies retry and fallback at the layers described above before a failure ever reaches you.
Because the agents are expert-built rather than assembled by each user from raw tool definitions, the most common error classes are handled in the build: schemas are kept in sync with the APIs they call, credentials are managed and refreshed, and transient timeouts and rate limits are absorbed by retry policies. A run that hits a genuine failure surfaces a clear result rather than a confusing wrong answer, and the people who maintain the agent see the trace and fix the root cause.
For you as a user, that means an agent runs your task and hands back a finished result in about 60 seconds, and you only pay when it runs: $1 equals 1,000 credits. The debugging discipline in this guide is what good agent building looks like under the hood. If you want the background on what makes a tool-using system an agent in the first place, what is an AI agent and the glossary cover the definitions.
FAQ
What is the fastest way to find which tool call failed?
Open the run trace and scan for the first step that returned an error or a non-success status, not the last one. The agent often keeps going after a failed call and produces a confusing final answer, so the symptom you see is downstream of the real fault. Read the trace top to bottom, find the earliest tool call whose response is an error, a timeout, or an empty result the agent did not expect, and start there.
What are the most common classes of agent tool error?
Six classes cover most failures: authentication and credential errors (expired token, missing scope), timeouts (the tool took too long to respond), malformed parameters (the agent sent a value in the wrong format), schema mismatch (the tool definition does not match what the API actually accepts), empty or unexpected results (the call succeeded but returned nothing usable), and rate limits (too many calls in a short window). Identifying the class tells you which layer to fix.
Should I fix a tool error in the prompt or in the tool definition?
Fix it at the layer where the fault actually lives. If the agent sent a wrong value because the instruction was vague, fix the prompt. If the tool schema describes a parameter incorrectly or is missing a required field, fix the schema. If the call fails on credentials, fix the connection, not the prompt. If the underlying service is flaky, add a retry or fallback. Patching a schema problem in the prompt usually fails again on the next variation.
How do I reproduce an agent tool error reliably?
Capture the exact inputs from the failed run: the user request, the tool name, and the parameters the agent sent. Replay that single tool call in isolation with the same parameters, outside the full agent loop. If it fails the same way, you have a deterministic reproduction and can fix it directly. If it succeeds in isolation, the fault is in how the agent built the call, which points you back to the prompt or the schema.
How do I stop the same tool error from happening again?
After the fix, add a guard at the layer that failed: input validation on parameters, a clearer schema description, a retry with backoff for transient errors, and a fallback path for tools that can be unavailable. Then add the failing case to a small regression set so a future change does not silently reintroduce it. Monitoring and traces let you catch recurrence before users do.