# 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. Last verified against MCP specification 2026-07-28: Tools on 2026-11-18.

## Error message you’ll see

```text
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: https://github.com/PrefectHQ/fastmcp/issues/5367

```text
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: https://github.com/modelcontextprotocol/typescript-sdk/blob/951fe5603a7ec0b2dcb6a0b95d92cd86f93ad9e5/packages/server/src/server/mcp.ts#L406

## 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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#output-schema)

## 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

```ts
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}
```

## 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](https://isokron.ai/mcp-check/checks/schema-pagination)
- [Schemas use JSON Schema 2020-12](https://isokron.ai/mcp-check/checks/spec-schema-dialect)
- [Update and delete tools take a version or precondition](https://isokron.ai/mcp-check/checks/surface-version-guard)
- [MCP tool input and output schemas](https://isokron.ai/mcp-check/checks/schema)

## Further reading

- [Do popular packaged MCP servers say whether a write happened?](https://isokron.ai/research/mcp-write-results-100-servers)

Counts toward: Schema and description quality.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
