Read tools declare an outputSchema
A tool may declare an outputSchema; when it does, it must return structuredContent that matches, which lets clients validate results and tells the model which fields come back.
Check schema-output-schema · Schema and description quality · default severity: advice · rubric 2.1.0
Error message you’ll see
Tool get_readme has an output schema but did not return structured contentMCP client SDKs (Python RuntimeError, TypeScript error), when a tool with an outputSchema returns only text. Where this was reported
Output validation error: Tool […] has an output schema but no structured content was providedTypeScript SDK 2.4.0 server, same case. Where this message comes from
What fails
An outputSchema lets clients validate results and tells the model which fields come back, for example the version an update needs.
The rule
Tools may also provide an output schema for validation of structured results.
How to fix it
Add an "outputSchema" and return matching "structuredContent".
- Declare outputSchema (zod object in TypeScript; a TypedDict or Pydantic return type in Python generates it).
- Return structuredContent matching it, and the same data as text content for older clients.
- Include fields later calls need, such as the version an update must send.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'get_issue',
{
title: 'Get issue',
description: 'Return one issue by ID, with its current version. Use when the user names an issue.',
inputSchema: z.strictObject({
issue_id: z.string().describe('Issue ID, for example ISS-42'),
}),
outputSchema: z.object({
issue_id: z.string().describe('Issue ID'),
title: z.string().describe('Title'),
state: z.string().describe('open or closed'),
version: z.number().int().describe('Send this as expected_version when updating'),
}),
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
},
async ({ issue_id }) => {
const result = { issue_id: '...', title: '...', state: '...', version: 0 };
return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
},
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
from typing import TypedDict
server = MCPServer("issues")
class Issue(TypedDict):
issue_id: str
title: str
state: str
version: int
@server.tool(
title="Get issue",
annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def get_issue(
issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
) -> Issue:
"""Return one issue by ID, with its current version. Use when the user names an issue."""
return {"issue_id": "...", "title": "...", "state": "...", "version": 0}Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
What does "has an output schema but did not return structured content" mean?
The tool declares an outputSchema, but a call returned only text content. Return structuredContent that matches the schema on every successful call, or remove the outputSchema.
Does the Python SDK create outputSchema automatically?
Yes. A tool function with a typed return value (a TypedDict, Pydantic model or dataclass) gets an outputSchema and returns structuredContent.
Related checks
- List and search tools take a limit or cursor
- Schemas use JSON Schema 2020-12
- Update and delete tools take a version or precondition
- All checks in MCP tool input and output schemas
Further reading
How this check is graded
It counts toward: Schema and description quality. See the rubric.
Last verified against MCP specification 2026-07-28: Tools on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere