Outputs, evidence and tool errors

The mechanism

A tool result should help the host reason accurately. ParcelOps returns an identifier, observation status and resource revision, rather than an unbounded backend response. The host can then distinguish a missing record from a stale observation or a failed lookup.

An output schema describes the structured result. Current MCP permits structured content to be any JSON value, but a small object is often easiest to evolve and inspect. If an output schema is declared, validate the result against it. Valid shape does not establish truth: the underlying source still needs provenance and authorization.

Keep text and structured output consistent. A text summary saying “resolved” alongside structured status “delayed” forces the client to choose between conflicting evidence. Generate both from the same validated application result rather than assembling them independently.

Worked example

The following is an application result fixture, not a full protocol envelope. Revision 7 is synthetic. found: false should have a documented shape rather than an ambiguous empty string. A real service should add an observation timestamp from its own clock and define which fields are safe to disclose.

{"id":"INC-104","found":true,
 "record":{"status":"delayed","revision":7},
 "provenance":{"kind":"synthetic_fixture","dataset":"parcelops-v1"}}

Practice: predict, inspect, explain

Offline exercise. Create present, absent, unauthorized and temporarily unavailable cases. For each, decide whether it is an application result or a tool error and whether a retry changes anything. Add a deliberately contradictory text summary and reject it in your fixture checks.

Expected observation: output validation catches shape errors but needs additional invariants to catch contradictions. A model cannot recover provenance that the server omitted. Write down the minimum evidence the final answer must cite, including when the record was observed and whether the data was synthetic.

Troubleshooting and trade-offs

Large outputs consume context and can conceal relevant fields. Prefer bounded projections and explicit follow-up capabilities. Avoid returning private exception traces or credentials in error content. If a backend response is truncated, say so rather than presenting a partial list as complete. Escaping or formatting output for display does not make embedded instructions trustworthy.

Interview practice

Completion check

Design four output cases with explicit failure semantics and no unsupported claim of a live lookup.

Sources and version notes

This edition targets MCP 2026-07-28, checked 6 October 2026. SDK examples are version-sensitive and labelled when not executed. Synthetic fixtures are learning material, not protocol conformance evidence.

• Official documentation: Tools
• Official documentation: Server concepts
• Official documentation: Security best practices