[FEATURE] Surface MCP tool outputSchema to the model; without it, return-value docs must be duplicated between prompts and the tool

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

This is a re-file of #54197 ("Surface MCP tool outputSchema to the model context, not just the renderer"), which was closed as inactive by the stale bot with an instruction to open a new issue if still relevant (https://github.com/anthropics/claude-code/issues/54197#issuecomment-4751196671). It is still relevant, and the behavior is unchanged as of Claude Code 2.1.220 (bundled with claude-agent-sdk 0.2.128).

MCP servers can declare a per-tool outputSchema (MCP spec 2025-06-18). Frameworks like FastMCP generate it automatically from the tool function's return type annotation, including per-field descriptions from the return model. Claude Code parses this schema and uses it internally (it caches a validator per tool and enforces that a tool declaring an output schema returns matching structuredContent), but the tool definition presented to the model contains only name, description, and input_schema. The model never sees the output schema or any of its field descriptions.

The practical consequence for anyone maintaining MCP servers used by more than one agent runtime: return-value documentation has to be duplicated. The schema on the return model is the natural single source of truth (field meanings, units, enums, which fields to check first), but because Claude Code drops it, the same information must be copied into the tool's description string and/or the system prompt. Depending on which backend drives the agent, the docs live in different places, and the duplicated copies drift out of sync with the actual return model.

Proposed Solution

Surface the declared outputSchema to the model as part of the MCP tool catalog. Either of these would solve it:

1. Append a rendered form of the output schema (including field descriptions) to the tool's description before it is sent to the model, or
2. Include the schema in the tool definition itself if/when the API grows a field for it.

Option 1 requires no API changes and could be gated behind a setting if context growth is a concern.

Alternative Solutions

• Duplicating the return-model field documentation into the tool description string, and keeping it in sync with the schema by hand. This works but defeats the purpose of outputSchema and drifts.
• Letting the model discover the response shape empirically (call once, observe, call again). This burns turns and context, and field semantics (units, enum meanings) are not discoverable from values alone.

Priority

Medium - Would be very helpful

Feature Category

MCP server integration

Additional Context

Verified against Claude Code 2.1.220: the model-facing tool definition is built as {name, description, input_schema}, and an explicit field allowlist (name, description, input_schema, cache_control) strips everything else before the request is sent. Meanwhile the embedded MCP client does consume outputSchema (validator cache plus the "Tool X has an output schema but did not return structured content" enforcement), so the schema is on the wire and parsed; it is only the model that never sees it.

The original issue #54197 contains a wire capture confirming the same asymmetry: structuredContent round-trips on the response side, but the pre-call discoverability half of MCP 2025-06-18 is dropped.