Retryable Metadata & Partial Results

When a tool or MCP server fails, the model has to decide what to do next. A generic status like "Operation failed" gives it nothing to reason about, so the only safe move is to abort or guess.

A structured error turns a dead end into a decision: should we retry, route around the failure, or escalate to a human? In this lesson you'll learn the four metadata fields that make that possible: errorCategory, isRetryable, attempted_query, and partial_results.

Every structured MCP error starts with one boolean: isError: true. This is the unambiguous signal that the tool result is a failure, not data.

Without it, the model may treat an error message as a legitimate answer and happily summarize the failure as if it were a result. The flag is the gate that activates all the recovery logic that follows.

errorCategory classifies why the call failed so the model can route intelligently. The four standard categories are:

• transient — a temporary fault (timeout, rate limit). Likely worth retrying.
• validation — the input was malformed. Fix the request, don't blindly retry.
• business — a domain rule blocked it (e.g. order already shipped).
• permission — the caller isn't authorized. Retrying won't help; escalate or re-auth.

The category drives the strategy; it doesn't make the decision alone.

isRetryable is the explicit yes/no on whether retrying could possibly succeed. It works with the category but encodes a sharper signal.

A transient timeout is usually isRetryable: true. A validation error is isRetryable: false — retrying the same bad input just fails again. Crucially, this lets the subagent recover transient faults locally instead of bubbling every hiccup up to the coordinator.

A subtle but exam-critical distinction: an access FAILURE is not the same as a valid EMPTY result.

• isError: true + transient → the query couldn't run. Consider a retry.
• isError: false + empty list → the query ran fine and there are genuinely no matches. Retrying is pointless and wasteful.

Generic errors blur this line. Structured metadata keeps "I couldn't look" cleanly separated from "I looked, nothing's there."

attempted_query records exactly what the tool tried to do — the SQL, the API call, the search string. This serves two jobs:

• It lets the model retry with feedback: send the original intent plus the error so a corrected query can be formed.
• It feeds provenance — you keep a claim-to-source trail of what was actually asked.

Remember: retry-with-feedback fixes format/structural mistakes. If the information is simply absent from the source, no amount of re-querying helps.

When a multi-step or multi-source operation fails halfway, the work done before the failure is still valuable. partial_results carries it forward.

Imagine a research subagent that queried five sources and the fifth timed out. Returning the four successful results plus the error means the coordinator can keep going — instead of discarding everything because one leg failed. Never abort the whole workflow on a single failure.

The metadata enables a clean two-tier strategy in hub-and-spoke systems:

• Recover transient faults locally inside the subagent — retry the isRetryable ones quietly.
• Escalate non-recoverable failures up to the coordinator, carrying the full structured context: failure type, attempted query, and any partial results.

The coordinator handles errors and routes. But it can only route well if the subagent hands it a structured signal instead of a bare exception or silence.

If you define the error as structured output, apply the schema rules carefully. Mark a field required only if it is always present. partial_results is often empty or absent on a hard failure — so don't force it as required, or the model may fabricate entries to satisfy the schema.

For errorCategory, use an enum with an "other" value plus a free-text detail field. That keeps classification clean today and extensible for failure modes you haven't met yet.

Metadata guides the model probabilistically (~90%). When a failure has financial, legal, or safety consequences, that isn't enough.

Use a PostToolUse hook to intercept the tool result before the model sees it, and enforce policy deterministically (100%). For example: if errorCategory is permission on a refund tool, block any retry and force escalation — don't leave it to the prompt to behave.

The worst thing you can do with a failure is hide it. Two failure modes to avoid:

• Silent suppression — swallowing the error and returning an empty or made-up result. Now the model can't tell a real "no matches" from a broken query.
• Aborting the whole workflow on one failed leg — throwing away every partial result.

Structured errors are the cure for both: they surface the failure and preserve what succeeded.

Apply what you've learned to a real multi-agent scenario.

Structured errors turn failures into routable decisions:

• isError — the gate that activates recovery logic.
• errorCategory — transient / validation / business / permission (+ "other") sets the strategy.
• isRetryable — the explicit retry hint; recover transient faults locally.
• attempted_query — enables retry-with-feedback and provenance (won't help if info is truly absent).
• partial_results — carry forward good data; never abort the whole workflow on one failure.

Mark only always-present fields as required, guard money/legal/safety failures with deterministic hooks, and never suppress errors silently. That's architect-grade error handling.