{"post":{"slug":"agent-tool-error-handling-2026","title":"Agent Tool Errors: Writing Failures a Model Can Recover From","excerpt":"Your tool returned \"Error: invalid request\". The agent has no idea what to change, so it retries the same call. Error messages are prompt surface, and most are written for humans reading logs.","category":"ai","date":"January 13, 2026","author":"ByteLedger Team","content":"<span class=\"dropcap\">A</span>n agent calls your tool and gets back `Error: invalid request`. It has no information about what was invalid, so it does the only thing available: tries again, identically. Gets the same error. Tries a third time with a small random variation. Burns budget, achieves nothing, and eventually gives up or hits a step cap.\n\nThe tool worked correctly. The error message was written for a developer reading a log file, and it is being read by a model that has to decide what to do next.\n\n## What changed in 2026\n\n- **Tool error text got recognised as prompt surface.** Teams started treating error strings with the same care as tool descriptions rather than as logging output.\n- **Structured errors spread.** Returning a machine-readable error type alongside human-readable text let agents branch reliably.\n- **Retry storms became visible.** Cost attribution made repeated identical failing calls show up as a line item.\n- **MCP and similar protocols standardised the shape.** Consistent error conventions across tool servers reduced per-tool handling.\n\n## What a useful error contains\n\n| Element | Why the model needs it |\n| --- | --- |\n| What went wrong | To know the call failed at all |\n| Which input was at fault | To know what to change |\n| What would be valid | To know what to change it to |\n| Whether retrying could help | To avoid a retry loop |\n| What to try instead | To make progress rather than stop |\n\nCompare two responses to the same failure:\n\n*\"Error: invalid request\"* — the model knows nothing.\n\n*\"Unknown status 'pending_review'. Valid values: open, closed, archived. Retrying with the same value will fail.\"* — the model can correct the call immediately, and knows not to retry blindly.\n\nThe second costs a few more tokens and saves several failed calls. On any agent doing repeated tool work, that trade is overwhelmingly favourable.\n\nListing valid options is the single highest-value addition. A rejected enum value with the allowed set attached converts a dead end into a one-step correction.\n\n## Retryable versus permanent\n\nThe distinction the model cannot infer and must be told.\n\n**Retryable:** rate limits, timeouts, transient service errors, temporary lock contention. Waiting and retrying may succeed.\n\n**Permanent:** malformed input, invalid values, missing permissions, a resource that does not exist. Retrying identically will fail identically, forever.\n\nAn agent that cannot distinguish them defaults to retrying, which is correct for the first category and pure waste for the second. Saying so explicitly in the error text — or better, in a structured field — removes the guesswork.\n\nRate limits deserve a specific note: include how long to wait. An agent told to retry without a duration will retry immediately, which makes the rate limit worse. The same reasoning as [thundering herd](/blog/thundering-herd-and-cache-stampede-2026), applied to one agent.\n\n## Never fail silently\n\nThe worst error handling is none. A tool that catches its own exception and returns an empty result, a default value, or `null` produces the most damaging outcome available: the agent believes it succeeded.\n\nIt then reasons from a wrong fact, builds on it, and produces a confident conclusion with no indication anything went wrong. This is exactly the mechanism of [context poisoning](/blog/context-poisoning-explained-2026), and it is self-inflicted.\n\nAn empty search result meaning \"no matches\" and an empty search result meaning \"the search service is down\" must be distinguishable. If they are not, the agent will conclude the corpus contains nothing on the topic and proceed accordingly.\n\nThe rule: return an error when something failed, always, even when returning something plausible would be easier.\n\n## Common mistakes\n\n- **Generic error text.** Nothing to act on.\n- **Stack traces.** Context consumed, no signal.\n- **Silent defaults on failure.** The agent believes a lie.\n- **No retryable indication.** Retry loops on permanent failures.\n- **Rate limits without a wait duration.** Immediate retry worsens it.\n- **Rejecting a value without listing valid ones.** Turns a correction into a guess.\n- **Inconsistent error shapes across tools.** The agent cannot learn one convention.\n\n## FAQ\n\n**Should errors be structured or prose?**\nBoth. A structured type lets your code branch reliably; prose lets the model understand. Returning a type field plus a clear sentence covers both consumers.\n\n**How verbose should they be?**\nLong enough to be actionable, short enough not to dominate context. A sentence or two with the specific offending value and the valid alternatives is usually right.\n\n**What about errors containing sensitive data?**\nRedact before returning. Error paths are a common leak route, and an error string with a customer identifier in it is now in the model context and your traces — see [PII redaction for LLMs](/blog/pii-redaction-for-llms-2026).\n\n**Should the agent see every error?**\nNot necessarily. Transient failures your code already retried successfully need not reach the model at all. Surface what the agent should act on.\n\n## Where to go next\n\nFor designing the tools these errors come from, read [tool schema design](/blog/tool-schema-design-2026). For the contamination silent failures cause, [context poisoning](/blog/context-poisoning-explained-2026), and for bounding retry loops, [agent token budgets](/blog/agent-token-budgets-2026).","hue":208,"metaTitle":"Agent Tool Errors: Failures a Model Can Recover From","metaDescription":"How to write tool error messages AI agents can act on, why retryable and permanent errors must be distinguishable, and what silent failures cost.","keywords":["agent tool errors","tool call error handling","llm error recovery","actionable error messages","retryable errors agent","silent failure llm","tool design","ai agents 2026"],"tldr":["**An error message is part of your prompt** — the model reads it and acts on it, so it should say what to do differently.","**Distinguish retryable from permanent** — a model that cannot tell will retry a malformed request forever.","**Return the valid options when a value is rejected** — listing them turns a guess into a correction.","**Never swallow errors into a plausible default** — a tool that returns empty on failure poisons the run silently.","**Skip:** raw stack traces. They consume context and tell the model nothing actionable."],"readTime":"4 min read","wordCount":843},"related":[{"slug":"tool-calling-reliability-2026","title":"Tool Calling Reliability: Making the Model Pick Right","excerpt":"Models call the wrong tool, invent arguments, and loop. Most of that is fixable by changing the tools rather than the prompt. Here is what actually works.","category":"ai","date":"June 26, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":204},{"slug":"tool-result-caching-2026","title":"Tool Result Caching: Not Fetching the Same Thing Twice","excerpt":"Agents re-fetch the same file, re-run the same query, and re-search the same term within a single run. Caching those results is the cheapest speedup available.","category":"ai","date":"August 17, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":201},{"slug":"agent-turn-taking-2026","title":"Agent Turn-Taking: Knowing When to Stop and Ask","excerpt":"An agent that never asks anything guesses at ambiguity. One that asks constantly is a worse interface than a form. Getting the boundary right is a design decision nobody makes deliberately.","category":"ai","date":"February 14, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":209}],"sameCategory":[{"slug":"agent-cost-attribution-2026","title":"Agent Cost Attribution: Finding Where the Tokens Went","excerpt":"A single monthly API bill tells you that agents are expensive. It does not tell you which feature, which customer, or which retry loop is responsible. That gap is fixable.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":220},{"slug":"human-in-the-loop-agents-2026","title":"Human-in-the-Loop Agents: Where to Put the Approval Gate","excerpt":"Approve everything and the agent is a slow autocomplete. Approve nothing and you have handed irreversible actions to a system that can be talked into things.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":197},{"slug":"reasoning-effort-controls-2026","title":"Reasoning Effort Controls: Tuning How Hard a Model Thinks","excerpt":"Fixed thinking budgets gave way to effort levels, and the default is rarely the right setting. Here is how the dial behaves and where each level actually belongs.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":210},{"slug":"retrieval-metrics-explained-2026","title":"Retrieval Metrics: Measuring the Half of RAG That Fails","excerpt":"When a RAG system answers badly, the retrieval usually failed before the model ever spoke. Measuring generation quality alone hides that entirely.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":215}],"newer":{"slug":"ynab-vs-mint-alternatives-2026","title":"YNAB vs Mint alternatives 2026: where to go after Mint shut down","excerpt":"Mint shut down in March 2024. Two years on, here are the apps that actually replaced it, ranked by what they do best — not by who shouts loudest.","category":"finance","date":"January 14, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":280},"older":{"slug":"ai-model-registry-2026","title":"AI Model Registry: Knowing What Is Actually Deployed","excerpt":"A model, a prompt, an adapter, and a configuration together determine behaviour. Tracking them as one versioned unit is the difference between reproducible and mysterious.","category":"ai","date":"January 13, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":217}}