CCA-F start here · Trap gym · When a tool fails

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

At a glance:
  • 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.

The useful one says: “The line dropped after three prices. Here they are. Their lines are often busy for a few minutes; I can ring back at ten, or check their website.” You can decide.
The vague one says “It didn't work.” The patient one rings back three times, then says “Couldn't get through,” and forgets to hand over the three prices.
The inventor says “They don't sell those.” The quitter throws the whole project folder in the bin because one call failed.

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.

result report answer Tool MCP server Subagent first to see it Coordinator decides what next User customer, committee isError: trueerrorCategoryisRetryableplain reasonpartial results retry a short bliplocally, then passup only what isstill unresolved,with what it has wait and retryuse another sourcego on, gap statedescalate(not: end the run) told the truth:what is done,what isn't,and what happensnext

In a single-agent chat there is no coordinator: the agent reads the tool result and decides itself. The same rules apply.

The one question to ask: after this failure, does the next decision-maker know what happened, what was tried and what is still usable?

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.

1. The failure

2. How it is handled

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

TrapWhat the wrong option looks likeWhy it's wrong
Inventing informationReturn 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 informationA 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-terminatingRaise an exception to a top-level handler that ends the workflowOne failure throws away all finished work and every chance to recover.
Retrying the unretryableBackoff on a policy refusal or a bad inputRules 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

Say what failed, whether to retry, what was tried and what you already have. Never dress a failure up as an empty success, and never end the whole run over one.

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.”

← All traps