@cyanheads/mcp-ts-core 0.2.2 → 0.2.3

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Protocol
 
-**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.2.2
+**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.2.3
 **npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) · **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
 
 > **Developer note:** Never assume. Read related files and docs before making changes. Read full file content for context. Never edit a file before reading it.
@@ -159,16 +159,32 @@ export const myTool = tool('my_tool', {
   description: 'Does something useful.',
   annotations: { readOnlyHint: true },
   input: z.object({ query: z.string().describe('Search query') }),
-  output: z.object({ result: z.string().describe('Search result') }),
+  output: z.object({
+    items: z.array(z.object({
+      id: z.string().describe('Item ID'),
+      name: z.string().describe('Item name'),
+      status: z.string().describe('Current status'),
+      description: z.string().optional().describe('Item description'),
+    })).describe('Matching items'),
+    totalCount: z.number().describe('Total matches before pagination'),
+  }),
   auth: ['tool:my_tool:read'],
 
   async handler(input, ctx) {
     const data = await fetchFromApi(input.query);
-    ctx.log.info('Query resolved', { query: input.query, resultCount: data.length });
-    return { result: data.summary };
+    ctx.log.info('Query resolved', { query: input.query, resultCount: data.items.length });
+    return data;
   },
 
-  format: (result) => [{ type: 'text', text: result.result }],
+  format: (result) => {
+    const lines = [`**${result.totalCount} results**\n`];
+    for (const item of result.items) {
+      lines.push(`### ${item.name}`);
+      lines.push(`**ID:** ${item.id} | **Status:** ${item.status}`);
+      if (item.description) lines.push(item.description);
+    }
+    return [{ type: 'text', text: lines.join('\n') }];
+  },
 });
 ```
 
@@ -176,7 +192,7 @@ export const myTool = tool('my_tool', {
 
 **Schema constraint:** Input/output schemas must use JSON-Schema-serializable Zod types only. The MCP SDK converts schemas to JSON Schema for `tools/list` — non-serializable types (`z.custom()`, `z.date()`, `z.transform()`, etc.) cause a hard runtime failure. Use structural equivalents instead (e.g., `z.string()` with `.describe('ISO 8601 date')` instead of `z.date()`). The linter validates this at startup.
 
-**`format`**: Maps output to `ContentBlock[]`. Omit for JSON stringify default. Additional formatters: `markdown()` (builder), `diffFormatter` (async), `tableFormatter`, `treeFormatter` from `/utils`.
+**`format`**: Maps output to MCP `content[]` — the only field most LLM clients (Claude Code, VS Code Copilot, Cursor, Windsurf) forward to the model. `structuredContent` (from `output`) is for programmatic use and is not reliably shown to the LLM. **Make `format()` content-complete** — render all data the model needs to reason about the result, not just a count or title. Omit for JSON stringify fallback. Additional formatters: `markdown()` (builder), `diffFormatter` (async), `tableFormatter`, `treeFormatter` from `/utils`.
 
 **Task tools:** Add `task: true` for long-running async operations. Framework manages lifecycle: creates task → returns ID immediately → runs handler in background with `ctx.progress` → stores result/error → `ctx.signal` for cancellation. See `add-tool` skill for full example.
 
@@ -448,6 +464,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 - **JSDoc:** `@fileoverview` + `@module` required on every file
 - **No fabricated signal:** Don't invent synthetic scores or arbitrary "confidence percentages." Surface real signal.
 - **Builders:** `tool()`/`resource()`/`prompt()` with correct fields (`handler`, `input`, `output`, `format`, `auth`, `args`)
+- **`format()` completeness:** `content[]` is the only field most LLM clients forward to the model — `format()` must render all data the LLM needs, not just a count or title
 - **Auth:** via `auth: ['scope']` on definitions (not HOF wrapper)
 - **Presence checks:** `ctx.elicit`/`ctx.sample` checked before use
 - **Task tools:** use `task: true` flag

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.2.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.28.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
+[![Version](https://img.shields.io/badge/Version-0.2.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.28.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 

package/dist/mcp-server/tools/utils/toolDefinition.d.ts

@@ -55,8 +55,16 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
     /** LLM-facing description. */
     description: string;
     /**
-     * Optional formatter mapping output to ContentBlock[].
-     * If omitted, the handler factory JSON-stringifies the output.
+     * Optional formatter mapping output to MCP `content[]` — the field LLM clients
+     * inject into the model's context. `structuredContent` (from `output`) is for
+     * programmatic/machine use and is NOT reliably forwarded to the model by most
+     * clients (Claude Code, VS Code Copilot, Cursor, Windsurf all read `content[]`).
+     *
+     * **Make `format()` content-complete.** If the LLM needs data to reason about
+     * the result, it must appear here — not just in the output schema. A thin
+     * one-liner (e.g., a count or title) leaves the model blind to the actual data.
+     *
+     * If omitted, the handler factory JSON-stringifies the output as a fallback.
      */
     format?: (result: z.infer<TOutput>) => ContentBlock[];
     /**
@@ -85,13 +93,25 @@ export type AnyToolDefinition = ToolDefinition<ZodObject<ZodRawShape>, ZodObject
  * const myTool = tool('my_tool', {
  *   description: 'Does something useful.',
  *   input: z.object({ query: z.string().describe('Search query') }),
- *   output: z.object({ result: z.string().describe('Search result') }),
+ *   output: z.object({
+ *     items: z.array(z.object({
+ *       id: z.string().describe('Item ID'),
+ *       name: z.string().describe('Item name'),
+ *       status: z.string().describe('Current status'),
+ *     })).describe('Matching items'),
+ *   }),
  *   auth: ['tool:my_tool:read'],
  *   annotations: { readOnlyHint: true },
  *   async handler(input, ctx) {
  *     ctx.log.info('Processing', { query: input.query });
- *     return { result: `Found: ${input.query}` };
+ *     return { items: await search(input.query) };
  *   },
+ *   // format() populates content[] — the only field most LLM clients read.
+ *   // Render all data the model needs; structuredContent is not forwarded.
+ *   format: (result) => [{
+ *     type: 'text',
+ *     text: result.items.map(i => `**${i.id}**: ${i.name} (${i.status})`).join('\n'),
+ *   }],
  * });
  * ```
  */

package/dist/mcp-server/tools/utils/toolDefinition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,EAC9D,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC;IAE/D,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qCAAqC;IACrC,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,YAAY,EAAE,CAAC;IACtD;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChG,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;AAM/F;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,EAAE,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,EAChG,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,GACrD,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAEjC"}
+{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,EAC9D,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC;IAE/D,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qCAAqC;IACrC,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,YAAY,EAAE,CAAC;IACtD;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChG,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;AAM/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,EAAE,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,EAChG,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,GACrD,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAEjC"}

package/dist/mcp-server/tools/utils/toolDefinition.js

@@ -15,13 +15,25 @@
  * const myTool = tool('my_tool', {
  *   description: 'Does something useful.',
  *   input: z.object({ query: z.string().describe('Search query') }),
- *   output: z.object({ result: z.string().describe('Search result') }),
+ *   output: z.object({
+ *     items: z.array(z.object({
+ *       id: z.string().describe('Item ID'),
+ *       name: z.string().describe('Item name'),
+ *       status: z.string().describe('Current status'),
+ *     })).describe('Matching items'),
+ *   }),
  *   auth: ['tool:my_tool:read'],
  *   annotations: { readOnlyHint: true },
  *   async handler(input, ctx) {
  *     ctx.log.info('Processing', { query: input.query });
- *     return { result: `Found: ${input.query}` };
+ *     return { items: await search(input.query) };
  *   },
+ *   // format() populates content[] — the only field most LLM clients read.
+ *   // Render all data the model needs; structuredContent is not forwarded.
+ *   format: (result) => [{
+ *     type: 'text',
+ *     text: result.items.map(i => `**${i.id}**: ${i.name} (${i.status})`).join('\n'),
+ *   }],
  * });
  * ```
  */

package/dist/mcp-server/tools/utils/toolDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmFH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,IAAI,CAClB,IAAY,EACZ,OAAsD;IAEtD,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2FH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,IAAI,CAClB,IAAY,EACZ,OAAsD;IAEtD,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Build tools, not infrastructure. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Node.js and Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -250,7 +250,7 @@
   "dependencies": {
     "@hono/mcp": "^0.2.4",
     "@hono/node-server": "^1.19.11",
-    "@modelcontextprotocol/ext-apps": "^1.3.1",
+    "@modelcontextprotocol/ext-apps": "^1.3.2",
     "@modelcontextprotocol/sdk": "^1.28.0",
     "@opentelemetry/api": "^1.9.1",
     "dotenv": "^17.3.1",

package/skills/add-tool/SKILL.md

@@ -55,7 +55,20 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
     return { /* output */ };
   },
 
-  format: (result) => [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  // format() populates MCP content[] — the only field most LLM clients forward
+  // to the model. structuredContent (from output) is for programmatic use only.
+  // Render ALL data the LLM needs to reason about the result.
+  format: (result) => {
+    const lines: string[] = [];
+    // Render each item with all relevant fields — not just a count or title.
+    // A thin one-liner (e.g., "Found 5 items") leaves the model blind to the data.
+    for (const item of result.items) {
+      lines.push(`## ${item.name}`);
+      lines.push(`**ID:** ${item.id} | **Status:** ${item.status}`);
+      if (item.description) lines.push(item.description);
+    }
+    return [{ type: 'text', text: lines.join('\n') }];
+  },
 });
 ```
 
@@ -192,6 +205,7 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 - [ ] Schemas use only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`)
 - [ ] JSDoc `@fileoverview` and `@module` header present
 - [ ] `handler(input, ctx)` is pure — throws on failure, no try/catch
+- [ ] `format()` renders all data the LLM needs (not just a count or title) — `content[]` is the only field most clients forward to the model
 - [ ] `auth` scopes declared if the tool needs authorization
 - [ ] `task: true` added if the tool is long-running
 - [ ] Registered in `definitions/index.ts` barrel and `allToolDefinitions`

package/skills/design-mcp-server/SKILL.md

@@ -193,7 +193,7 @@ output: z.object({
 ```
 
 - **Truncate large output with counts.** When a list exceeds a reasonable display size, show the top N and append "...and X more". Don't silently drop results.
-- **Use the `format` function for readable summaries** while keeping the full structured data in the output object for programmatic use.
+- **`format()` is the model-facing output — make it content-complete.** MCP `content[]` (populated by `format()`) is the only field most LLM clients forward to the model. `structuredContent` (from `output`) is for programmatic/machine use and is not reliably shown to the LLM. A thin `format()` that returns only a count or title leaves the model blind to the actual data. Render all fields the LLM needs to reason about or act on the result. Use structured markdown (headers, bold labels, lists) for readability.
 
 #### Convenience shortcuts for complex inputs
 
@@ -364,6 +364,7 @@ Execute the plan using the scaffolding skills:
 - [ ] Parameter `.describe()` text explains what the value is, what it affects, and tradeoffs
 - [ ] Input schemas use constrained types (enums, literals, regex) over free strings
 - [ ] Output schemas designed for LLM's next action — chaining IDs, post-write state, filtering communicated
+- [ ] `format()` renders all data the LLM needs — `content[]` is the only field most clients forward to the model (not just a count or title)
 - [ ] Error messages guide recovery — name what went wrong and what to do next
 - [ ] Annotations set correctly (`readOnlyHint`, `destructiveHint`, etc.)
 - [ ] Resource URIs use `{param}` templates, pagination planned for large lists

package/skills/polish-docs-meta/references/readme.md

@@ -242,6 +242,7 @@ Table of environment variables. Include framework vars only if the server uses n
 | `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
 | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
 | `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
+| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
 | `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |
 | `OTEL_ENABLED` | Enable OpenTelemetry. | `false` |
 ```

package/templates/CLAUDE.md

@@ -75,7 +75,12 @@ export const searchItems = tool('search_items', {
     return { items };
   },
 
-  format: (result) => [{ type: 'text', text: `Found ${result.items.length} items` }],
+  // format() populates content[] — the only field most LLM clients forward to
+  // the model. Render all data the LLM needs, not just a count or title.
+  format: (result) => [{
+    type: 'text',
+    text: result.items.map(i => `**${i.id}**: ${i.name}`).join('\n'),
+  }],
 });
 ```
 

package/templates/src/mcp-server/tools/definitions/echo.tool.ts

@@ -21,5 +21,8 @@ export const echoTool = tool('template_echo_message', {
     return { message: input.message };
   },
 
+  // format() populates MCP content[] — the only field most LLM clients forward to
+  // the model. Render ALL data the LLM needs here, not just a summary or count.
+  // This echo tool is trivial; real tools should render every relevant field.
   format: (result) => [{ type: 'text', text: result.message }],
 });