From f24bf9741215f665e70709b80e0cf268bcdc26cc Mon Sep 17 00:00:00 2001 From: olaservo Date: Sat, 1 Aug 2026 21:30:22 -0700 Subject: [PATCH] Say "structured content", not "structured output" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The spec never uses the phrase "structured output". It defines two separate things under Tool Result: "Structured Content" (the `structuredContent` field) and "Output Schema" (the `outputSchema` field). Collapsing them into "structured output" conflates the two. It is also actively confusing here. In LLM tooling "structured output" means constrained decoding — making the *model* emit conforming JSON. These clients call a model API, so a reader could reasonably take the phrase to mean the tool constrains the model's response, which is the opposite of what is going on: the tool describes the shape of its own result. Headings and prose now say "structured content". References to real identifiers are left alone: the Python SDK's own docs page is called Structured Output and lives at docs/servers/structured-output.md, and its decorator parameter is `structured_output`. Co-Authored-By: Claude Opus 5 --- mcp-client-ruby/README.md | 2 +- weather-server-ruby/README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/mcp-client-ruby/README.md b/mcp-client-ruby/README.md index acecd56..f73e74f 100644 --- a/mcp-client-ruby/README.md +++ b/mcp-client-ruby/README.md @@ -2,7 +2,7 @@ See the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial for more information. -## Structured output +## Structured content The spec says clients SHOULD validate structured results against the schema the tool declares, and this SDK's client does not do it for you — `MCP::Client::Tool#output_schema` hands back the raw schema from the wire and nothing checks results against it. So the client compiles each declared schema once at connect time with `MCP::Tool::OutputSchema.new` and validates every non-error result. diff --git a/weather-server-ruby/README.md b/weather-server-ruby/README.md index bf7013c..e24378a 100644 --- a/weather-server-ruby/README.md +++ b/weather-server-ruby/README.md @@ -2,7 +2,7 @@ See the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial for more information. -## Structured output +## Structured content Both tools declare an `output_schema` and return `structured_content`. `get_forecast` returns an object; `get_alerts` returns a top-level JSON array, which protocol revision `2026-07-28` is the first to allow — see [Structured Content](https://modelcontextprotocol.io/specification/draft/server/tools#structured-content) in the spec. @@ -14,7 +14,7 @@ The tools also return a human-readable `content` block. When you pass your own ` ## Known limitation: strict `2026-07-28` clients reject this server -The `mcp` gem never emits the `resultType` field on results. The 2026-07-28 schema makes it mandatory — "Servers implementing this protocol version MUST include this field" — so a client that enforces the revision rejects every response, including `tools/list`, before it ever reaches the structured output. +The `mcp` gem never emits the `resultType` field on results. The 2026-07-28 schema makes it mandatory — "Servers implementing this protocol version MUST include this field" — so a client that enforces the revision rejects every response, including `tools/list`, before it ever reaches the structured content. There is no way to set it from user code: `MCP::Server` accepts `ttl_ms:` and `cache_scope:` for the SEP-2549 cache hints, but nothing for `resultType`. The gem's own client does not check the field, so the gap is invisible when a Ruby client talks to a Ruby server, and only appears cross-SDK.