# Tool call errors in AI agents: how to detect, classify and reduce them

A tool call can fail with a 400, a 429 or a timeout. It can also return 200 with nothing useful inside. Here is how to tell the types apart, measure them per call, and stop the ones that keep coming back.

By Mohammad Al-Rasheed, CTO & Co-Founder at Moda. Published 2026-11-12.

Canonical: https://moda.dev/tool-call-errors

The interactive example on the web page shows six constructed tool calls, not customer data, one for each failure type: a bad argument (HTTP 400, send the validation message back to the model), the wrong tool (HTTP 200, no retry helps), a rate limit (HTTP 429, retry after the Retry-After delay), an expired token (HTTP 401, reconnect the credential), a payment provider error on a refund (HTTP 503, the refund may have gone through, so check status or retry with the same idempotency key), and an empty search result (HTTP 200, change the query or tell the user).

## What is a tool call error?

A tool call error happens when an AI agent asks a tool to do something and the call does not give the agent what it needed. The tool might reject the arguments, time out, refuse the credential, pass along an error from a downstream API, or return nothing useful. A call can also succeed and still be wrong, when the agent picked a tool that cannot do what the user asked.

You will see the same problem under several names: tool calling errors, function calling errors (OpenAI's original name for the feature), tool call failures, or just tool failures. They describe the same thing.

Every tool call can go wrong in one of three places:

- **The model's request:** it chose the wrong tool, or sent arguments that are malformed, invented or wrong for the user.
- **The tool's execution:** the call timed out, hit a rate limit, failed authentication, or a service behind the tool returned an error.
- **The agent's handling of the result:** the tool reported a failure or an empty result, and the agent carried on as if it had succeeded.

The third place is the one that reaches users. Most of this guide is about catching the first two before they get there.

### Each API reports a failed call differently

Before you can count tool call errors, your system has to know a call failed. Model APIs do not agree on how to say so.

- **Anthropic:** a `tool_result` block carries an optional `is_error` field: "Set to `true` if the tool execution resulted in an error" ([handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls)).
- **OpenAI:** the function output "should typically be a string, where the format is up to you (JSON, error codes, plain text, etc.)" ([function calling](https://developers.openai.com/api/docs/guides/function-calling)). There is no error flag. If your tool returns `{"error": "..."}` as an ordinary string, nothing downstream counts it unless your code does.
- **Model Context Protocol:** the [tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) separates protocol errors (JSON-RPC errors for unknown tools, malformed requests and server errors) from tool execution errors, reported in the result with `isError: true` (API failures, input validation errors and business logic errors).

So record your own failure flag on every call, from the status, the exception and the output, whichever API you use. Your tool call error rate is only as good as that flag.

## Six types of tool call failures

Group failures by what went wrong, not by which tool raised them. The type decides whether a retry can help and who has to change something. The interactive example above walks through one call of each type.

### 1. Schema or argument errors

The model sends a call the tool cannot accept: a missing required field, a string where a number belongs, a relative date like "last Tuesday" where the tool wants `2026-11-03`, or a parameter that does not exist. These are the classic LLM tool calling errors, and they cluster around format-sensitive fields such as dates, IDs, currencies and enums.

A related case passes validation: the arguments are well formed but wrong. The order ID is valid, it just belongs to a different customer. A schema check cannot see that.

**What to check:** validate arguments before you execute the call. Return the validation message to the model as the tool result, so it can correct the call. Watch for the same field failing across many traces; that points at the schema or the description, not at one bad turn.

### 2. The wrong tool

The user asks to cancel an order and the agent calls `get_order_status`. Every field is valid and the call succeeds. Nothing returns an error, so error-based monitoring never sees it.

Wrong-tool calls come from overlapping tools, vague names and descriptions that do not say when a tool should not be used. Anthropic's tool-writing guidance puts it plainly: "When tools overlap in function or have a vague purpose, agents can get confused about which ones to use" ([writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)).

**What to check:** compare what the user asked for with the tools the agent called. Look for traces where a required action never happened, and for a read tool called in place of a write tool.

### 3. Timeouts and rate limits

A timeout means the tool did not answer in time. On a read, you can usually try again. On a write, a timeout leaves the outcome unknown: the payment API may have refunded the customer and failed to send the response.

A rate limit is an HTTP 429, "Too Many Requests", which [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585.html) defines for a client that sent too many requests in a given amount of time. The response may include a `Retry-After` header with a delay in seconds or a date ([RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after)). Agents hit rate limits more than ordinary clients because they call tools in parallel, loop, and retry.

**What to check:** separate timeouts on reads from timeouts on writes. Track 429s per tool and per upstream provider, and look at how many calls the agent made in the minutes before them.

### 4. Authentication and permission errors

A 401 or 403 means the credential behind the tool expired, was revoked, or lacks the scope for this action. The model cannot fix it, and every user of that tool hits the same wall until someone does.

**What to check:** auth errors tend to arrive all at once, across every call to one integration. Alert on them by integration rather than waiting for a rate to drift. Make sure the agent tells the user the action did not happen.

### 5. Downstream API errors

The tool is often a thin wrapper around someone else's API, and that API returns errors of its own. A 500 or 503 from a payment provider is usually transient, but on a write it leaves the outcome as unknown as a timeout does: the refund may have gone through before the error. A 404 for a missing record or a 422 for a business rule ("refund exceeds the original charge") is a real answer that the agent should relay, and retrying it changes nothing.

**What to check:** keep the downstream status code and error body on the call record. A raw `Error: request failed` cannot be classified later.

### 6. Silent empty results

The tool returns HTTP 200 with an empty list, or a message like "No matching articles". No exception is raised. If the agent then answers anyway, the answer comes from the model's memory instead of your data.

Not every empty result is a failure. A search that explicitly found nothing did not get the agent what it needed. A list of reminders that is empty because the user has none is a correct answer. The difference is whether the call was supposed to find something.

**What to check:** read the output, not only the status. Treat an explicit "no results" from a search or lookup as an unsuccessful call, then check what the agent told the user next.

## Retries and fallbacks: which tool call errors to retry

A retry repeats the same request. It helps only when the cause was temporary. For most tool failures it repeats the mistake, adds latency, and can double a write.

- **Retry transient errors with backoff.** For 429s, and for timeouts and 5xx responses on reads or idempotent writes, wait before retrying and cap the attempts. Honor `Retry-After` when it is present. Add jitter so parallel calls do not retry in lockstep; the AWS Architecture Blog's [analysis of exponential backoff and jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) shows why the randomness matters.
- **Send argument errors back to the model.** The model can correct a bad argument if the error says what was wrong. Anthropic notes that when a tool request is invalid or missing parameters, "Claude will retry 2–3 times with corrections before apologizing to the user." Cap that loop yourself instead of relying on it.
- **Do not retry auth errors.** The same credential fails the same way. Refresh it once if your integration supports refresh, then stop and tell the user.
- **Never blindly retry a write that timed out or got a 5xx.** The write may have completed before the error. Read the status first, or send the retry with the same idempotency key. Stripe's [idempotent requests](https://docs.stripe.com/api/idempotent_requests) exist so a client can safely retry "without accidentally performing the same operation twice."
- **Change the query after an empty result.** The same query returns the same nothing. Broaden it once, then tell the user nothing was found.
- **Do not retry a wrong-tool call.** The call worked. The agent needs a different tool, which is a prompt or tool-design change.

Here is that policy as code. It assumes your harness has already turned the raw error into one of these kinds:

```typescript
type ToolError =
  | { kind: 'argument'; message: string }
  | { kind: 'rate_limit'; retryAfterSeconds?: number }
  | { kind: 'downstream'; status: number; message: string; idempotent: boolean }
  | { kind: 'timeout'; idempotent: boolean }
  | { kind: 'auth' }
  | { kind: 'empty_result' }

type Step =
  | { action: 'retry'; afterMs: number }
  | { action: 'return_to_model'; message: string }
  | { action: 'check_status_first' }
  | { action: 'stop'; tellUser: string }

const MAX_ATTEMPTS = 3

// Full jitter: a random wait between zero and an exponential cap.
const backoffMs = (attempt: number) => Math.random() * Math.min(30_000, 1_000 * 2 ** attempt)

function nextStep(error: ToolError, attempt: number): Step {
  if (attempt >= MAX_ATTEMPTS) {
    return { action: 'stop', tellUser: 'Say which action did not complete.' }
  }
  switch (error.kind) {
    case 'argument':
      return { action: 'return_to_model', message: error.message }
    case 'rate_limit':
      return { action: 'retry', afterMs: error.retryAfterSeconds !== undefined ? error.retryAfterSeconds * 1_000 : backoffMs(attempt) }
    case 'downstream':
      if (error.status < 500) return { action: 'return_to_model', message: error.message }
      // A write can complete before the service fails, so treat it like a timeout.
      return error.idempotent ? { action: 'retry', afterMs: backoffMs(attempt) } : { action: 'check_status_first' }
    case 'timeout':
      return error.idempotent ? { action: 'retry', afterMs: backoffMs(attempt) } : { action: 'check_status_first' }
    case 'auth':
      return { action: 'stop', tellUser: 'The connection to this service needs to be renewed.' }
    case 'empty_result':
      return { action: 'return_to_model', message: 'No results. Broaden the query once, or tell the user nothing was found.' }
  }
}
```

Two things this does not do. It does not decide whether a write is idempotent; the tool has to know that. And it does not detect a wrong tool, because a wrong-tool call never raises an error.

### Fallbacks

A fallback swaps the failing path for another one: a secondary search index, a cached copy, a different provider, or a handoff to a person. Fallbacks keep the conversation going. They also hide the original failure from anyone looking only at outcomes.

Record the first failure even when the fallback or the retry succeeds. Otherwise a tool that fails on every first attempt looks healthy, and you pay for it in latency, tokens and rate limits.

## How to detect tool call errors in production

Detection starts with the record of the call. For each tool call, capture the tool name and version, the arguments, the status, the full output or error text, the latency, and the trace it belongs to. Include the user's request and the agent's next reply, because a tool failure matters most in how the agent handled it. Redact secrets and personal data at the boundary, and keep stable IDs.

Then layer the checks, cheapest first:

- **Status and exceptions.** Non-2xx responses, timeouts and thrown errors. Necessary, and nowhere near enough.
- **Output inspection.** A 200 whose body says `"error"`, `"status": "failed"`, or "No matching articles". A batch call where one nested request failed while the others succeeded.
- **Argument validation.** Arguments that fail the tool's schema, checked before execution so the model gets a useful message instead of a stack trace.
- **Behavioral checks.** The same call repeated with the same arguments and the same result. A required action that never happened. A final answer that does not mention a failed write. These need the trace, not just the call.

Keep the raw output. A count of failures without the text that caused them will not help anyone fix anything.

## Classifying tool failures at scale

A thousand failed calls produce a thousand slightly different error strings. `ETIMEDOUT`, `Read timed out after 30000ms` and `504 Gateway Timeout` are one problem. `invalid date` and `placed_after must be an ISO 8601 date` are another. Counting raw messages gives you a long list nobody reads.

Classify each failed call into a category that names the cause and where the fix lives. Two levels work well:

- **A family** you can count and alert on: argument error, wrong tool, timeout, rate limit, authentication, downstream error, empty result, or unknown.
- **A category** specific enough to act on, such as "relative date passed to search_orders" or "expired token for the ticketing integration", with the likely cause and the first thing to try.

Rules on status codes and error text classify the transport failures cheaply. Normalizing messages (stripping IDs, timestamps and numbers) before grouping collapses most duplicates. A language model can label the long tail, provided every label quotes the exact text in the call's output that supports it. A label without evidence cannot be checked, and a reviewer will stop trusting the whole list after the first wrong one.

A few rules keep the categories honest:

- **Classify every attempt.** A failure that a retry recovered still cost time and tokens, and it will come back.
- **Keep an unknown category.** Forcing every failure into a known type hides new ones.
- **Check a sample by hand.** Measure how many labels a reviewer agrees with, per family, before you alert on them.
- **Keep the categories stable.** Renaming or merging them every week breaks every trend line that uses them.

## Metrics: tool call error rate and tools affected

Pick the unit first. Each metric answers a different question, and they move differently.

- **Failure rate per tool call:** failed calls divided by all recorded calls, successes included, in the window. This is the tool call error rate most dashboards mean. Break it down by tool.
- **Failure rate per trace, task or turn:** the share of runs with at least one failed call. This tells you how many conversations hit trouble.
- **Tools affected:** the number of distinct tools with at least one failure in the window. When it jumps, look for a shared dependency such as an auth provider or a gateway.
- **Failures over time, by tool:** spikes line up with deploys, provider incidents and expired credentials.
- **Recovery rate:** the share of failed calls followed by a successful retry or fallback in the same trace.
- **Failures that reached the user:** failed calls where the agent's reply hid the failure or claimed success. This is the one that matters most, and it needs the trace to measure.

The units can tell very different stories. Take an illustrative week of 2,000 traces that make 10,000 tool calls between them. If 150 calls fail, the per-call failure rate is 1.5%. If those 150 failures fall in 120 traces, the per-trace rate is 6%. Both numbers are correct. Report the denominator next to every rate, and do not compare a per-call rate from one dashboard with a per-trace rate from another.

Retries distort per-call rates. An agent that retries every failure three times turns one failure into four failed calls. Count the first attempt separately, or measure per trace as well.

## How a failed tool call becomes a bad answer

Users rarely see the tool error itself. They see the agent's next reply, and that is where a failed call does its damage.

- **It answers anyway.** The help-center search found nothing, and the agent states a refund window from memory. The answer is fluent and wrong.
- **It reports success.** The refund call timed out and the agent says "Your refund is on its way." Nothing in the trace shows it happened.
- **It loops.** The agent calls the same failing tool six times. The user waits, the token bill grows, and the rate limit gets worse.
- **It doubles a write.** A retry without an idempotency key creates a second ticket, a second email, or a second refund.
- **It does the wrong thing successfully.** The wrong tool returns 200, and the agent tells the user their order is processing when they asked to cancel it.

Benchmarks show how far tool use still has to go even without production noise. In [τ-bench](https://arxiv.org/abs/2406.12045), which simulates users talking to tool-using agents in retail and airline domains, the authors report that "even state-of-the-art function calling agents (like gpt-4o) succeed on <50% of the tasks." That is a benchmark result, not a production failure rate, but it is a useful reminder that a valid call is not the same as a finished task.

When every call succeeds and the task still fails, the problem is a silent failure; see [silent failures in AI agents](/silent-agent-failures) for how to find those.

## How to reduce tool call errors

### Write schemas the model cannot misread

Use enums for closed sets, explicit formats for dates and IDs, required fields, and `additionalProperties: false`. Turn on strict mode where your provider has it. OpenAI says "Setting `strict` to `true` will ensure function calls reliably adhere to the function schema, instead of being best effort." Anthropic's strict tool use "guarantees that tool inputs always match your schema exactly."

Strict mode fixes the shape of the arguments. It does not check their meaning: a well-formed order ID can still be the wrong order, and a valid call can still go to the wrong tool.

### Validate inputs before you execute, and return useful errors

Validate on the tool side as well; the MCP specification says servers "MUST" validate all tool inputs. When validation fails, tell the model what was wrong and what to try. Anthropic suggests messages like "Rate limit exceeded. Retry after 60 seconds." in place of a bare "failed", and its tool-writing guidance asks for errors that "clearly communicate specific and actionable improvements, rather than opaque error codes or tracebacks."

### Describe tools for a reader who has never seen your system

The model chooses tools from their names and descriptions. Anthropic calls detailed descriptions "by far the most important factor in tool performance" and suggests at least three to four sentences per tool: what it does, when to use it and when not to, what each parameter means, and what it does not return ([define tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools)).

Keep the tool set small and distinct. OpenAI suggests aiming "for fewer than 20 functions available at the start of a turn at any one time," while calling that a soft suggestion. Prefix names by service, merge tools that overlap, and say in each description which neighboring tool to use instead.

### Make writes safe to retry

Give every consequential write an idempotency key, generated once per user intent and reused on every retry. Return the operation's status in the tool output so the agent can check before it acts again.

### Turn production failures into evals

After you confirm a recurring failure, save the smallest trace that reproduces it: the user request, the tool definitions at the time, the failed call and its output. Add a passing case next to it, so a change that stops calling the tool altogether does not look like a win. Replay your prompt, schema or tool change against those traces before it ships, using recorded tool responses or a sandbox for anything with side effects. Then keep watching the failure rate for that tool after release.

## How Moda finds and classifies tool failures

Moda is infrastructure for catching AI agent mistakes in production and turning them into evals. Tool failures are one of the failures it detects in your production traces.

**Recording.** Tool calls are recorded as they arrive with your traces: the tool name, whether the call succeeded, and the error text.

**Classification.** Moda classifies a trace's tool calls once the trace has been quiet for about an hour, and at least every four hours on a trace that keeps going. It reads each call's output, not only its status, so a 200 whose output records an explicit error, or a search that explicitly found nothing, can still count as a failure, while an empty list that is a correct answer does not. Every failure it records has to quote the call's own output or error text, and a label whose quote is not in that output is not kept. Each attempt is classified on its own, including attempts a later retry recovered. In a workspace set to analyze a sample of its traces, classification covers only the sampled traces.

**Categories.** Each failure category has a label, the failure family it belongs to, a description of the underlying error, its likely cause, and a recommended action.

**The Tool Failures tab.** On the Signals page, the Tool Failures tab shows Total Failures, the failure rate (per tool call by default, and you can switch it to per turn, task or trace), and Tools Impacted. A Failures over time chart plots failure events by tool, stacked or grouped. Below it, each tool lists its failures, traces, categories and when it last failed. Opening a tool shows its categories and failure events, and each event links into the trace at the failed call.

The same data is available through the Data API (`GET /tool-failures` and `GET /tool-failures/:toolName`) and the CLI (`moda detections tools`). The built-in Tool failures signal can drive alerts to Slack, Linear or email, and recurring failures are grouped into problems ranked by how many users they affect, with the traces behind each one.

A wrong-tool call succeeds, so tool-failure classification will not flag it. Describe it as a custom signal in plain language instead, for example: "The user asked to cancel an order and the agent never called cancel_order." When your team changes a prompt, tool or model, replay the change against the traces that failed and compare pass rate, latency and tokens. Your team reviews the result and decides what ships.

Two limits to plan around. Classification waits for a trace to go quiet, so keep your own real-time alerting for outages that need a page within minutes. And Moda can only classify what your traces contain: if tool outputs are not captured, there is nothing to read.

### Start with one agent and its busiest tools

Connect traces through the [Moda SDKs, OpenTelemetry, or HTTP ingestion](https://docs.moda.dev/ingestion/overview), including tool calls and their outputs. Open the Tool Failures tab, sort by failures, and read the categories for the top tools before setting an alert threshold.

[Request a Moda workspace](/signup) to try it with your agent. Access is invite-only and requests are reviewed by the Moda team. If you would rather walk through your own tool failures with us first, [book a demo](https://cal.com/team/moda/demo-meeting?overlayCalendar=true), or [explore Monitor](/monitor).

## Questions engineers ask

### Are function calling errors and tool calling errors the same thing?

Yes. OpenAI introduced the feature as function calling; Anthropic, the Model Context Protocol and most agent frameworks call it tool use or tool calling. The failure types in this guide apply to all of them.

### Does strict mode eliminate tool call errors?

No. Strict mode constrains the arguments to your schema, which removes malformed and missing arguments. It does not prevent the wrong tool, a valid but wrong value, timeouts, rate limits, auth errors, downstream errors or empty results.

### What is a normal tool call error rate?

There is no universal number. It depends on your tools, their upstream services and how your agent retries. Measure the rate per tool, with its denominator, and watch how it changes after each release.

### Should the model see the raw error?

It should see an error it can act on: what failed, why, and what to try next. Strip secrets, internal hostnames and long stack traces. Keep the raw error in your own records for debugging.

### How do I stop an agent from looping on a failing tool?

Cap attempts per tool per turn in the harness, not only in the prompt. Detect repeated identical calls with identical results. When the cap is reached, return an error that tells the model to stop and explain to the user what could not be done.

### Does a failed call that a retry recovered still count?

Count it. It cost latency, tokens and rate-limit headroom, and the next retry might not recover.

## A checklist for your next tool failure review

- Record a failure flag, the full output or error text, and the trace for every tool call.
- Read outputs, not only status codes, so 200s with errors and explicit empty results count.
- Classify failures by type: argument, wrong tool, timeout, rate limit, auth, downstream, empty result.
- Retry only transient errors, with backoff, jitter, a cap, and `Retry-After`.
- Give consequential writes idempotency keys, and check status before retrying a write that timed out or got a 5xx.
- Report failure rates with their unit and denominator, per tool, and track tools affected.
- Check what the agent told the user after each failed call.
- Turn confirmed failures into eval cases, and replay your fix against them before it ships.

Start with the tool that fails most often this week, and read ten of its failed calls in full.
