Machine-Parseable Tool Output

The 2025-2026 MCP spec introduced outputSchema and structuredContent, allowing tools to return both human-readable text and machine-parseable JSON simultaneously. This is critical for agentic pipelines where downstream tools need to consume structured data rather than parsing free-form text.

outputSchema & structuredContent

server.tool(
  "get_stock_price",
  "Fetch the current stock price for a ticker symbol",
  { ticker: z.string().describe("Stock ticker, e.g. AAPL") },
  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 }
    };
  },
  { outputSchema: { type: "object", properties: { ticker: { type: "string" }, current: { type: "number" }, change: { type: "number" }, volume: { type: "number" } } } }
);

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.