claude-code - 💡(How to fix) Fix [FEATURE] Surface MCP tool outputSchema to the model context, not just the renderer [1 participants]

What

MCP servers can declare a per-tool outputSchema in tools/list (introduced in spec 2025-06-18, PR modelcontextprotocol#371). Claude Code reads this — it's used internally for renderer validation of tool_use_result (visible via the safeParse flow that triggered #41361) — but it is not included in the tool catalog presented to the model.

The model receives only:

{ name, description, parameters }   // parameters = inputSchema

outputSchema is dropped before reaching the model.

Why this matters

When a model uses an MCP tool for the first time, it has no way to know what shape will come back. The schema is on the wire, the harness has parsed it, the validator uses it server-side — but the model itself has to discover the response shape empirically (call once, observe, sometimes call again). For chained tool-use and structured-output workflows this adds avoidable round-trips and burns context.

structuredContent on the response side does already round-trip (the model receives the typed object, not just markdown text) — so half of MCP 2025-06-18's discoverability story works in Claude Code today. The asymmetry is just on the pre-call side.

Repro

Any MCP server emitting outputSchema. Confirmed by tools/list wire capture (outputSchema present) plus an in-session prompt asking the model to print the literal outputSchema for a registered tool — the model reports it sees only parameters, no outputSchema.

Ask

Include outputSchema (raw, or as a synthesized compact prose summary appended to description) in the tool catalog passed to the model alongside each tool's name, description, and parameters.

Spec posture

This is permitted-but-not-required: the 2025-06-18 spec uses MUST only for the server-side emission and SHOULD only for client-side validation. The "helps … LLMs … properly parse and utilize the returned data" line is advisory benefit, not a conformance clause. So Claude Code is spec-compliant today — filing as a feature request, not a bug.

Ecosystem precedent

• VS Code's MCP host has the same gap; tracking PR microsoft/vscode#285882 (open) wires it through.
• OpenAI Codex CLI shipped per-turn output schemas for the assistant's final output (openai/codex#8377) — different surface, but proves the wiring is feasible.
• MCP Inspector displays outputSchema in its UI (modelcontextprotocol/inspector#456 merged).

Adjacent issues seen during search (not duplicates of this ask)

• #41361 — renderer regression on outputSchema mismatch (different surface)
• #25081 — earlier servers-getting-dropped issue, fixed
• #4427, #14465, #15412, #24742 — all about structuredContent plumbing on the result side

None ask for surfacing outputSchema in the model-facing catalog.