Carry source outcomes intact to the coordinator

Learning objective

Distinguish failed source access from a successful query returning no matches in propagated results.

Core idea

For an architect designing multi-agent research, an empty list is not enough information to decide whether a source was checked. A completed search with zero matches and a search that timed out can both leave the worker with no documents. Only the completed search supplies evidence about what that query found.

Preserve the execution outcome separately from the findings. The coordinator needs to know whether a query completed before interpreting its result count. If you collapse a timeout into an empty success, downstream synthesis can turn “not checked” into “nothing exists.” If you label every zero-match search as an error, recovery spends effort repeating valid work.

See 2.2.4 for this distinction where a tool returns its result; this lesson keeps it intact as the result travels from specialist to coordinator.

The distinction is about the attempted query, not universal absence. A successful search that finds no matching document supports “no matches for this query in this source.” It does not prove that no relevant document exists elsewhere or under different terminology. See 5.3.2 for the complete failure report and 5.3.3 for recovery ownership.

How it works

Preserve the tool outcome first

Carry the client tool’s tool_result.is_error signal and explanatory content into the specialist report; see 2.2.4 for the tool-level outcome contract. The propagation requirement is to preserve both the execution outcome and any surviving findings, rather than summarize every operation with no documents as an empty success.

Anthropic handles server-tool errors itself, so you do not send client is_error results on their behalf. For web search, Handle tool calls lists too_many_requests for rate limits, invalid_input for invalid query parameters, max_uses_exceeded for the tool-use limit, query_too_long for excessive query length, and unavailable for an internal error. These codes indicate failed operations, not completed searches with zero matches. Preserve the observed code in the specialist’s report so the coordinator can distinguish temporary access problems from a request that needs correction.

Define query-level states

Use an application-defined outcome field for each attempted query. For example, your report can distinguish completed from access_failed, while a separate matches field records retrieved items. These names are your contract, not Anthropic API enum values. Give them to the specialist through AgentDefinition.prompt when defining an Agent SDK subagent.

The following outcome matrix prevents result counts from carrying two meanings:

A source can be partially covered. If a worker reads an official release successfully and then fails to access its supplementary tables, the release remains evidence. The tables remain unchecked. Reporting one aggregate empty list would discard the successful portion and hide the failed portion.

Carry scope through the handoff

The Agent SDK subagent documentation explains that intermediate calls and results remain inside the subagent’s conversation; its final message returns to the parent. That makes the final report a decision interface. Do not assume the coordinator will reconstruct the source outcome from a tool trace that the specialist never summarized.

For each search, retain the source, actual query, filters that affect coverage, execution outcome, and retrieved findings. If a document was unavailable, say which document or endpoint was inaccessible. If a query completed with zero matches, say what you searched rather than replacing the query with a broad conclusion.

When the coordinator delegates synthesis, pass these outcome records alongside the findings. A synthesizer that receives only documents cannot tell whether an omitted topic was searched unsuccessfully, never checked, or inaccessible. Keep the successful query’s scope and the failed query’s cause attached to their respective topics so the final comparison can state a limited negative finding or an unresolved gap without confusing them. See 5.3.4 for the reader-facing coverage annotations.

These are application report requirements. The SDK’s AgentDefinition.prompt communicates them; it does not make a source’s response semantically correct. Your source adapter establishes whether access succeeded, and the specialist preserves that evidence in its report.

Key distinctions and trade-offs

Access outcome versus evidence outcome: A timeout describes execution. Zero matches describes a completed search. Neither establishes the truth of the wider research claim by itself.

Zero matches versus incomplete coverage: A completed query is resolved at its stated scope. The overall topic can still require additional queries. A source access failure leaves even the attempted scope unresolved.

Partial findings versus fabricated completion: Findings retrieved before a failure can remain useful. Calling the entire assignment successful because some findings exist hides unfinished work.

Explicit outcome records add a little handoff detail, but remove ambiguity that otherwise forces the coordinator to guess. Keep the records focused on decisions: the source and query that completed, the source and query that failed, and the findings each actually produced. A long execution transcript is not required to preserve those distinctions.

Architecture / decision scenario

A lead research agent compares regional requirements for hospital heat-response plans. One specialist searches an official regional publication catalogue. Another reads national guidance. The catalogue specialist completes a query for one region and finds no matching publication. Its next query, for another region, times out before the catalogue responds.

The first outcome becomes completed with zero matches in the application report. The specialist states the catalogue, query, and filters. The coordinator can broaden that query later if the assignment needs wider coverage, but it does not treat successful execution as a transient failure.

The second outcome becomes access_failed, with the timeout and attempted query preserved. The coordinator has learned nothing about whether the second region publishes a plan. It chooses recovery using the structured context taught in 5.3.2, rather than synthesizing an absence claim.

Meanwhile, the national-guidance specialist returns relevant documents. The coordinator retains them. In the final comparison, it distinguishes “no matching publication in the completed catalogue search” from “regional catalogue access failed; publications not assessed.” A reader can then see both the evidence and the boundary of the investigation.

If the catalogue adapter instead catches every exception and returns an empty array, both regional rows appear identical. The defect is not poor wording at synthesis time: the adapter has already destroyed the evidence needed to interpret the results. Correct the outcome contract before trying to improve the final prompt.

Common exam traps

• Returning an empty success after a source timeout because no documents arrived.
• Treating every zero-match query as a failure that needs transport retries.
• Turning a scoped search result into a claim that no evidence exists anywhere.
• Combining completed and failed searches into one undifferentiated source count.
• Assuming the parent automatically receives all intermediate subagent tool results.
• Applying client tool_result.is_error handling to server tools without checking their documented response shape.

What to remember

First ask whether the query completed. Then interpret its findings within that query’s scope. Preserve access failure, completed zero matches, and partial coverage as separate outcomes from the source adapter through the specialist’s final report. A missing answer must not become an answer of “none.”

Knowledge check

References

• Anthropic, Handle tool calls.
• Anthropic, Subagents in the SDK.