Structured Content & Tool Annotations — Advanced Features

Machine-Parseable Tool Output

Introduced in 2025-06-18 and standardized on JSON Schema 2020-12 in 2025-11-25+, outputSchema and structuredContent allow tools to return both human-readable text and validated machine-parseable JSON simultaneously. This is critical for agentic pipelines where downstream tools consume typed JSON rather than parsing free-form prose.

outputSchema & structuredContent

server.registerTool(
  "get_stock_price",
  {
    description: "Fetch the current stock price for a ticker symbol",
    inputSchema: z.object({ ticker: z.string().describe("Stock ticker, e.g. AAPL") }),
    outputSchema: z.object({ ticker: z.string(), current: z.number(), change: z.number(), volume: z.number() }),
    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
  },
  async ({ ticker }) => {
    const price = await fetchStockPrice(ticker);
    return {
      content: [{ type: "text", text: `The price of ${ticker} is $${price.current}` }],
      structuredContent: { ticker, current: price.current, change: price.change, volume: price.volume }
    };
  }
);

The content array is displayed to the user in the Host UI. The structuredContent is consumed programmatically by downstream agents or tools - enabling reliable data pipelines without brittle text parsing.

Tool Annotations

Tool annotations are metadata hints that describe a tool's behaviour to the client. They do not affect execution - they inform the Host about safety characteristics for smarter approval workflows.