What does an MCP tools/call return, and when is structuredContent required?

## The two channels of a tool result A `CallToolResult` has two payload channels that answer two different questions. **`content`** — an ordered array of content blocks, the *readable* channel. This is what the host feeds back into the conversation as the tool's output. Block types include: - `text` — plain text; by far the most common. - `image` and `audio` — base64 data plus a `mimeType`. - `resource_link` — a URI naming a resource the client can then fetch with `resources/read`, used when the payload is large or the client may not need it. - an embedded `resource` — the resource's contents inlined directly into the tool result. **`structuredContent`** — the *typed* channel: a single JSON object intended for programmatic consumption by the host, not primarily for reading. Plus the flag **`isError`**, which marks the result as a tool execution failure while remaining a successful JSON-RPC result. ## When structuredContent is required It is driven entirely by the tool definition. A `Tool` entry in `tools/list` may declare an `outputSchema` — a JSON Schema object, exactly parallel to `inputSchema`. If a tool declares one, its results MUST include `structuredContent` that validates against that schema, and clients SHOULD validate what they receive. If a tool declares no `outputSchema`, `structuredContent` is optional and most tools simply return content blocks. Declaring an `outputSchema` is a promise, so declare it only when the shape really is stable. The payoff is real: the host can bind fields to UI, downstream code can consume typed values without regex-scraping prose, and a mismatch is detectable rather than silently mis-parsed. For compatibility, a server returning `structuredContent` typically also serialises the same JSON into a `text` block in `content`, because a client that only knows how to read content blocks would otherwise see an empty tool output. That duplication is intentional and cheap. ## Choosing what to put where - Returning a paragraph of prose the model should reason about? `content` with a `text` block. - Returning rows of records the host will render as a table? `structuredContent` with an `outputSchema`, mirrored as text. - Returning a 40 MB CSV? A `resource_link` block, so the client decides whether to pull it. Inlining it burns context for everyone. - Returning a chart the user should see? An `image` block. The deciding question is who consumes it. Everything in `content` is heading for the model's context window, so size discipline there is real engineering, not tidiness. ## Errors and the structured channel On a failure the server sets `isError: true` and explains in `content`. It should not fabricate a `structuredContent` value that happens to satisfy `outputSchema`, because that makes a failure indistinguishable from a real result to any consumer that only validates the schema. ## Revision 2026-07-28 specifics Every result in this revision carries a required `resultType`. An ordinary tool result is `resultType: "complete"`; clients MUST treat its absence — which happens when talking to an older server — as `"complete"`. A tool that cannot finish without more input from the client instead returns the interim `"input_required"` result type, and a tool running under the `io.modelcontextprotocol/tasks` extension may return `"task"`. Both are separate mechanisms; the ordinary success path is `"complete"`. Note also what a tool result does **not** carry: `ttlMs` and `cacheScope`. Those belong to `CacheableResult`, which `ListToolsResult` extends but `CallToolResult` does not. Listing your tools is cacheable; invoking one is not — an invocation has side effects and a moment-in-time answer, and caching it would be wrong by default. ## A worked shape A weather tool with an `outputSchema` of `{ temperatureC: number, conditions: string }` returns `structuredContent: { "temperatureC": 14.5, "conditions": "overcast" }` and, alongside it, a text block reading `{"temperatureC":14.5,"conditions":"overcast"}` or a friendlier `14.5 °C, overcast`. The host binds the structured values to a widget; the model reads the text. ## What interviewers listen for The strong answer names both channels, ties `structuredContent` to the *tool's declared* `outputSchema` rather than to a client request, mentions `resource_link` as the escape hatch for large payloads, and knows that a tool result is not a cacheable result.