Return failures the coordinator can act on

Learning objective

Return failure category, attempted query, partial findings, and recovery alternatives rather than generic or silently suppressed errors.

Core idea

For an architect defining specialist handoffs, a failure report is an input to the coordinator’s next decision. “Search unavailable” states that something failed but withholds the information needed to choose a useful response. A report that names the cause, attempted query, surviving findings, and alternatives lets the coordinator adapt without repeating all completed work.

The four parts answer different questions. The failure category explains what prevented completion. The attempted query identifies the operation that failed. Partial findings preserve what the specialist actually established. Recovery alternatives propose ways to finish or narrow the assignment. None substitutes for another.

Anthropic documents instructive tool errors and specialist output requirements, but it does not prescribe the application fields used here. Define those fields in your own handoff contract. See 5.3.1 for access versus empty results, 2.2.2 for the category and retryability metadata, and 1.3.4 for the broader evidence-handoff design.

How it works

Put the contract in the specialist prompt

The Agent SDK’s AgentDefinition.prompt defines the specialist’s role and behavior. Use it to require an explicit outcome for each attempted query and the four failure-context elements. Anthropic’s multi-agent research engineering article also describes giving each subagent an objective, output format, tool and source guidance, and task boundaries.

An output requirement matters because the SDK isolates intermediate tool calls and results inside the subagent. The parent receives the final message, so a specialist that experienced several failures can still return a polished summary that conceals them. Require the report to carry unresolved operations alongside successful findings.

At the client-tool boundary, tool_result.is_error: true marks execution failure and tool_result.content explains it. Anthropic recommends including what went wrong and what to try next. At the specialist boundary, preserve that meaning in the application’s report rather than reducing the error to a generic final status.

Make each field answer a decision

The following fields are an illustrative application contract, not fields automatically supplied by the Messages API or Agent SDK:

Do not infer a category solely from missing documents. A source adapter that reports a temporary timeout supports errorCategory: "transient" with the timeout recorded as its cause; an empty list alone does not. When the cause is uncertain, report the observed failure instead of inventing a diagnosis.

The query should be reproducible enough to distinguish retries from changed work. “Searched statistics” is insufficient if the actual request bundled two countries, a year filter, and a publication type. Preserve those details so a proposed country-by-country search is visibly different from repeating the failed request.

Preserve findings and attempts separately

Partial findings need content and attribution, not only a count. “Six sources found” does not tell the coordinator whether any source addresses the missing question. Give a concise account of each useful finding and the source that supports it; keep broader attribution mechanics in 1.3.4.

Record local recovery attempts in attemptedSteps, following 2.2.5, with their outcomes so the coordinator does not unknowingly repeat an exhausted path. That attempt history supplements the four required elements. It should identify what was tried, not become a substitute for the attempted query or the evidence itself.

An alternative must be concrete. “Try again” is weak after repeated unchanged timeouts. “Split the two-country query into separate country requests” identifies a changed operation. “Read the tables in an already retrieved official report” identifies an alternate route. “Deliver the supported trend and mark the missing country figures” identifies a partial completion with an explicit limit.

Alternatives are proposals, not permissions. A worker should not suggest bypassing access controls or treating a less authoritative source as equivalent without saying so. The coordinator evaluates whether each option still serves the original research objective.

Key distinctions and trade-offs

Error signal versus error context: is_error: true marks a failed client-tool execution. It does not automatically supply the four-part specialist report. You need both the signal and enough detail to act on it.

Partial evidence versus partial prose: Retrieved, attributable findings are salvageable evidence. A half-written conclusion with missing support is not equivalent evidence merely because it contains text.

Recovery proposal versus completed recovery: An alternative describes what might work next. It must not appear among completed findings until the proposed work actually succeeds.

A compact report reduces coordination cost, but compressing away query scope or surviving evidence makes recovery blind. Prefer a short structured account with concrete fields over either a generic failure or an unfiltered execution log. The coordinator needs information that changes a decision, not every internal action.

Architecture / decision scenario

A research specialist must compare official heat-related hospital admissions statistics for two countries. It retrieves two ministry reports and several relevant studies, then a combined statistics query times out. Local recovery also fails.

Its final report identifies errorCategory: "transient" with a source timeout as the cause, preserves the exact two-country query and year filter, and records that the local attempts did not complete. Under partialResults, it summarizes the supported regional trend and names the two ministry reports. It does not claim that those reports contain the missing country totals until someone reads the relevant tables.

Under recoveryAlternatives, it proposes separate country queries, direct analysis of the retrieved reports, or delivery of the trend with a country-statistics gap. The coordinator can now compare distinct routes. If splitting the query succeeds for one country, it adds that result without rerunning the studies that already completed.

Contrast that handoff with “search unavailable.” The coordinator would not know that usable documents survived, which query failed, or whether a different route had already been tried. Contrast it with an empty success: that version would conceal the failure and could produce an unsupported claim that the official figures do not exist.

The structured report also supports an honest partial delivery if recovery cannot finish. The coordinator passes both supported findings and unresolved questions to synthesis, where 5.3.4’s coverage annotations preserve the failure’s meaning for the reader.

Common exam traps

• Returning a failure category without the attempted query or its scope.
• Reporting partial findings as a count without content or attribution.
• Proposing alternatives that are indistinguishable from already exhausted attempts.
• Treating a specialist’s recovery proposal as evidence that recovery succeeded.
• Returning an empty success to avoid disrupting the coordinator.
• Assuming is_error: true automatically constructs an actionable multi-agent report.

What to remember

Return cause, attempted query, surviving evidence, and concrete alternatives together. The coordinator can then repair a query, route to another source, or accept qualified partial completion. Generic errors hide choices; suppressed errors hide the need to choose at all.

Knowledge check

References

• Anthropic, Handle tool calls.
• Anthropic, Subagents in the SDK.
• Anthropic, How we built our multi-agent research system.