Skip to content
IsoKron

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

Error
Tool get_readme has an output schema but did not return structured content

MCP client SDKs (Python RuntimeError, TypeScript error), when a tool with an outputSchema returns only text. Where this was reported

Error
Output validation error: Tool […] has an output schema but no structured content was provided

TypeScript 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.

Source: MCP specification 2026-07-28: Tools

How to fix it

Add an "outputSchema" and return matching "structuredContent".

  1. Declare outputSchema (zod object in TypeScript; a TypedDict or Pydantic return type in Python generates it).
  2. Return structuredContent matching it, and the same data as text content for older clients.
  3. Include fields later calls need, such as the version an update must send.

TypeScript SDK

TypeScript
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

Python
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.

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