When a tool fails
A tool times out, a service is down, or a rule says no. Every option in the question handles it somehow: a retry, a message, a safe-looking default, a hard stop. The trap is picking a handling that loses information (what failed, what was tried, what was already found) or, worse, invents it.
D5 Context Management & ReliabilityD2 Tool Design & MCPExam guide 5.3 and 2.2About 15 minutes
- Tool failure: Return a structured error that says what failed and whether a retry can help; never return an empty success, a generic "failed" or a crash.
- Empty result or failure: "No results" and "couldn't reach the system" are different answers: report a failure as a failure with what was tried, and an empty search as a valid empty result.
Start here: the assistant and the phone call
You ask an assistant to phone a supplier for five prices. After three prices, the line drops. Here are five assistants.
Agents work the same way. A tool's error result, and whatever a subagent passes up, is the only thing the next decision-maker sees. If it says what failed, whether a retry can help, what was tried and what is already in hand, the coordinator can recover. If not, it guesses, or acts on something false.
In a single-agent chat there is no coordinator: the agent reads the tool result and decides itself. The same rules apply.
- Transient (timeout, outage): retry a short blip locally; if it persists, return a structured error with the attempted query, partial results and alternatives.
- Business rule (policy refusal): not retryable; return the reason in plain words and the alternative.
- Validation (bad input): say what was wrong, so the caller fixes the input instead of repeating the call.
- Never report “couldn't reach it” as “found nothing”, and don't end the whole run over one failure.
Words in the question that tell you which way to lean
Points to structured error
- “intelligent recovery”, “the coordinator decides what next”
- “partial results”, “finished work is thrown away”
- “the same text it returns for…”, “no results found” during an outage
- “retries every failure”, “tells the customer the system is down”
Tells you the category
- times out, unreachable, outage → transient, retryable
- policy, forbids, cut-off, limit → business, not retryable
- wrong format, invalid ID → validation, fix the input
- seconds later it works → retry locally first
Try it: one failure, five handlings
Pick a failure, then pick how it is handled. The trail shows what the tool returns, what reaches the decision-maker, what it does, and what the user is finally told. The diagram above shows where your handling acts.
The delays are illustrative, chosen to show the shape. They are not measurements. The exam guide's point is that structured error context lets the coordinator recover, while generic statuses, silent empty results and run-ending exceptions each lose or falsify information.
Things to try: Search times out + Empty result marked success: read what the committee is told. Then + Retry with backoff: the official sample's trap. Then + Structured error. Last, Business-rule refusal + Generic: a rule becomes “the system is down”.
The four traps
| Trap | What the wrong option looks like | Why it's wrong |
|---|---|---|
| Inventing information | Return an empty list or “not found” marked as success when the call failed | “We couldn't check” becomes “there is none”, and the agent acts on it as fact. |
| Losing information | A uniform “Operation failed”; retry with backoff, then a generic “unavailable” | The decider can't tell a blip from a rule, and the partial results never arrive. |
| Over-terminating | Raise an exception to a top-level handler that ends the workflow | One failure throws away all finished work and every chance to recover. |
| Retrying the unretryable | Backoff on a policy refusal or a bad input | Rules and wrong inputs don't change on retry. Only transient errors are worth retrying. |
Practice: three exam-style questions
Answer first, then open “Think it through”.
Rule to remember
Exam guide 5.3: “Structured error context (failure type, attempted query, partial results, alternatives) enables coordinator recovery.” and “Generic statuses hide context; silently suppressing errors or terminating on single failure are both anti-patterns.” Exam guide 2.2: “Uniform "Operation failed" prevents good recovery decisions.”