Retryable Errors, Subagent Recovery and Empty Results

1.Retryable vs non-retryable: give the agent what it needs to decide

Claude's tool-use documentation shows how the agent's reaction follows the error text. When the result says a required location parameter is missing, Claude calls the tool again with the gap filled. When the result says "ConnectionError: the weather service API is not available (HTTP 500)", Claude tells the user it couldn't get the weather and suggests trying again later. The same flag leads to two different recoveries, because the text tells the two cases apart.

Now replace both messages with "Operation failed". The agent can't tell a fixable argument from an outage, so it guesses. It might resend a request that will never succeed, burning turns on retries. Or it might give up on one that a corrected argument would have fixed. That is why uniform error responses rule out good recovery decisions: the agent's choice can only be as good as the information in the result.

The exam expects tools to make that information explicit and machine-readable: an errorCategory (transient, validation, permission), an isRetryable boolean, and a human-readable description. Those field names come from the exam guide. Neither the MCP specification nor the Claude docs define them. What the protocol does provide is somewhere to put them. A CallToolResult can carry structuredContent, described as a JSON object holding the result as machine-readable data and returned alongside content. The text in content still matters, because it is what the model reads as the explanation.

Business-rule violations need extra care. They are not retryable, so the result should say so clearly (the exam phrases this as retriable: false). The description should also be something the agent can pass on to a customer. The tutorial's calendar tool rejects an event with too many attendees, and Claude responds: "I tried to schedule the all-hands but the calendar only allows 10 attendees per event," then offers to split the session. Because the rule was stated plainly, the agent could explain it and suggest a way forward instead of retrying.

Sources123

2.Recover locally in the subagent and escalate only what's left

In a multi-agent system, the same reasoning decides where an error gets handled. A subagent that hits a transient failure is best placed to retry it, because it already has the context of the call. Passing every timeout up to the coordinator fills the coordinator's context with noise it can't act on any better. The exam's rule: retry transient failures inside the subagent, and send up to the coordinator only the errors the subagent couldn't resolve. When you do escalate, include the partial results and a record of what was attempted, so the coordinator can decide to reroute, retry elsewhere or report to the user without repeating work.

The sources don't describe this coordinator pattern directly. They do show the platform applying the same principle of keeping partial work. In Claude Code, if a rate limit, overload or server error cuts off a foreground subagent that has already produced text, the Agent tool returns that partial output with a note that the subagent was cut off. For a background subagent, the message Claude receives when it ends names the API error and includes the subagent's last output. In both cases the parent gets the error and the work done so far, not just a bare failure. Design your own subagent reports the same way.

Sources4

3.Access failures vs valid empty results

The last distinction runs in the opposite direction: a result that looks like a failure but isn't one. A query can fail to run because the database was unreachable or access was denied. Or it can run correctly and find nothing. These need opposite treatment. The first is an access failure, and the agent has to decide whether to retry. The second is a successful answer, "there are no matches", and the agent should report it as a fact.

The schema settles which is which. isError records whether the tool call ended in an error, and if it is not set, the call is treated as successful. A search that ran and matched zero records did not end in an error, so it should come back as a normal result whose content says no matches were found, with the flag left unset. Setting isError: true on an empty result misleads the agent. It may retry a query that already worked, or apologise to the user for a system failure that never happened. The reverse mistake is just as bad. If an unreachable backend returns an empty list with no flag, the agent will confidently report "nothing found" when it actually knows nothing.

Sources5

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A search that returns zero matches should be flagged with isError: true so the agent knows nothing came back.Why is that wrong?

   isError means the call ended in an error. A query that ran successfully and found nothing is a valid result, and flagging it makes the agent retry or apologise for a failure that didn't happen.

   Covered in Access failures vs valid empty results

2. 2.Any error flagged with isError should simply be retried until it succeeds.Why is that wrong?

   A business-rule violation gives the same answer on every retry. The right recovery is to explain the rule to the user, as Claude does when told the calendar caps attendees at 10.

   Covered in Retryable vs non-retryable: give the agent what it needs to decide