Implement SEP-2200: Clarify tool result content visibility

[felixweinberger]

This is a tracking issue for implementation of SEP-2200.

[mattzcarey]

Status — SEP-2200 (Clarify tool result content visibility)

Track: C — independent, starts now.
Spec: SEP-2200 PR was closed, but the normative content still landed in docs/specification/draft/server/tools.mdx via other commits. The spec page treats this as a real release-1 SEP.

What's done

• Nothing in main enforcing the new rules. packages/core/src/types/spec.types.ts currently has the old prose (isError: true → "any errors that originate from the tool SHOULD be reported inside the result object").

Outstanding (acceptance criteria, summary)

• R-2200-4 (wire): Tool that returns structuredContent SHOULD also return a content representation of the same information. Remove the SDK's auto-JSON-stringify of structuredContent into content (the old inspector behavior from change step name #1089).
• R-2200-5 (wire): When outputSchema is defined AND result is not an error, server MUST provide structuredContent conforming to the schema. The "not an error" qualifier is new — if isError=true with no/non-conforming structuredContent, SDK MUST NOT reject.
• R-2200-6 (sdk): Clients SHOULD NOT validate structuredContent against outputSchema when isError=true. (Today the client validator likely throws on outputSchema mismatch regardless of isError.)
• R-2200-1 (guidance): Clients SHOULD NOT forward both content and structuredContent verbatim to the model.
• R-2200-7 (guidance): When both present they SHOULD be semantically equivalent.
• R-2200-8 (guidance): Conversational/agentic clients SHOULD use content, fall back to structuredContent if empty.
• R-2200-9 (guidance): Programmatic/typed clients SHOULD prefer structuredContent.
• R-2200-10 (guidance): isError=true → error message in content; structuredContent MAY be omitted.

Suggested first PR

1. Lift the "auto-stringify structuredContent into content" branch in the SDK helper and replace it with explicit caller behavior.
2. In the client validator, gate outputSchema validation on !result.isError.
3. Update JSDoc on CallToolResult.structuredContent to reference the new prose.

Coordination

• Touches the same file as Implement SEP-2106: Tools inputSchema & outputSchema Conform to JSON Schema 2020-12 #2192 (spec.types.ts). Bundling the structuredContent widening (SEP-2106 R-2106-6) with the visibility rules (SEP-2200) avoids duplicate review of the same lines.
• No cross-track dependencies.

[norika1207-lab]

This looks worth pinning down as a protocol-level regression rather than only an implementation bug.

For tool result content visibility, the acceptance test I would want is a minimal client/server fixture that records the exact JSON-RPC or HTTP exchange, then asserts both the wire result and the local lifecycle state after the failure path. In MCP deployments, the dangerous failures are often not just wrong return values; they are pending requests, dropped notifications, mismatched session state, or errors that get translated into a generic response and become impossible to diagnose.

A useful fix boundary would preserve three signals: the protocol error sent to the peer, the local exception or cancellation reason available to application code, and a trace/log field that ties the two together. That makes the behavior debuggable for agent hosts without requiring every host to special-case this SDK detail.

[mattzcarey]

Closing: SEP-2200 was declined — the spec PR (modelcontextprotocol/modelcontextprotocol#2200) was closed unmerged on 2026-05-25 after the Core Maintainer vote was re-run, with the stated preference to instead fix the underlying tools/call interface with polymorphic return types in a future spec revision. The draft spec contains no visibility language to implement (the adjacent structured-content guidance is covered by SEP-2106 / #2249). If a successor SEP lands, it should get its own tracking issue.