@frontmcp/skills 1.3.0 → 1.4.1

package/catalog/create-tool/examples/23-tool-with-ui-filesource-tsx.md

@@ -0,0 +1,112 @@
+---
+name: 23-tool-with-ui-filesource-tsx
+level: advanced
+description: 'Tool with a `.tsx` widget in a separate file via the `FileSource` form — the recommended pattern for any React widget. Path anchored with `import.meta.url` so it survives any cwd.'
+tags: [ui, ui-widgets, FileSource, tsx, import.meta.url, host-detect]
+features:
+  - 'Pointing `template` at a sibling `.tsx` file via the `FileSource` form `{ file: ... }`'
+  - "Anchoring the path to the tool source with `fileURLToPath(new URL('./...widget.tsx', import.meta.url))` so `process.cwd()` doesn't matter"
+  - "Leaving `resourceMode` unset — the framework host-detects (`'inline'` for Claude, `'cdn'` for others)"
+  - "Naming the widget `*.widget.tsx` so the scaffolded `tsconfig.json`'s `exclude` keeps it out of the server typecheck"
+---
+
+# Tool With Ui Filesource Tsx
+
+Tool with a `.tsx` widget in a separate file via the `FileSource` form — the recommended pattern for any React widget. Path anchored with `import.meta.url` so it survives any cwd.
+
+For any React widget, FileSource is the right pattern. The widget lives in its own `.widget.tsx` file with its own React imports; the tool decorator just points at it.
+
+> **Prerequisite:** `@frontmcp/ui` installed at the same version as `@frontmcp/sdk`. Without it, server-side bundling fails — the framework injects an auto-generated React mount that imports `McpBridgeProvider` from `@frontmcp/ui/react`.
+
+## Code
+
+```typescript
+// src/apps/main/tools/sales-chart/sales-chart.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+export const inputSchema = { year: z.number().int().min(2000).max(2100) };
+export const outputSchema = {
+  year: z.number(),
+  monthly: z.array(z.object({ month: z.string(), revenueUsd: z.number() })),
+};
+export type SalesChartInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type SalesChartOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
+```typescript
+// src/apps/main/tools/sales-chart/sales-chart.tool.ts
+import { fileURLToPath } from 'node:url';
+
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+import { inputSchema, outputSchema, type SalesChartInput, type SalesChartOutput } from './sales-chart.schema';
+
+// Anchor the widget path to THIS source file — bare relative paths resolve
+// against process.cwd() (issue #444), which fails in any non-trivial layout.
+const widgetPath = fileURLToPath(new URL('./sales-chart.widget.tsx', import.meta.url));
+
+@Tool({
+  name: 'sales_chart',
+  description: 'Render a yearly sales bar chart',
+  inputSchema,
+  outputSchema,
+  ui: {
+    widgetDescription: 'Monthly revenue chart',
+    template: { file: widgetPath },
+    // resourceMode is intentionally UNSET — framework host-detects: 'inline' for Claude
+    // (React bundled in, widget renders under Claude's CSP), 'cdn' for OpenAI / ChatGPT /
+    // Cursor / MCP Inspector (smaller payload from esm.sh). Issue #456.
+    hydrate: false, // SSR-only — dodges React error #418 in iframe sandboxes
+  },
+})
+export class SalesChartTool extends ToolContext {
+  async execute(input: SalesChartInput): Promise<SalesChartOutput> {
+    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    return { year: input.year, monthly: months.map((month, i) => ({ month, revenueUsd: 10_000 + i * 1_250 })) };
+  }
+}
+```
+
+```tsx
+// src/apps/main/tools/sales-chart/sales-chart.widget.tsx
+import { useEffect, useRef } from 'react';
+
+type Props = { output: { year: number; monthly: Array<{ month: string; revenueUsd: number }> } };
+
+export default function SalesChartWidget({ output }: Props) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    if (!canvasRef.current) return;
+    const ctx = canvasRef.current.getContext('2d');
+    if (!ctx) return;
+    // …simple bar chart, no external deps so it runs everywhere
+    ctx.fillStyle = '#3b82f6';
+    output.monthly.forEach((m, i) => {
+      const barHeight = (m.revenueUsd / 25_000) * 280;
+      ctx.fillRect(i * 28 + 8, 300 - barHeight, 20, barHeight);
+    });
+  }, [output]);
+
+  return (
+    <div style={{ padding: 16, fontFamily: 'system-ui' }}>
+      <h2 style={{ margin: 0 }}>Sales — {output.year}</h2>
+      <canvas ref={canvasRef} width={360} height={320} style={{ marginTop: 12 }} />
+    </div>
+  );
+}
+```
+
+## What This Demonstrates
+
+- Pointing `template` at a sibling `.tsx` file via the `FileSource` form `{ file: ... }`
+- Anchoring the path to the tool source with `fileURLToPath(new URL('./...widget.tsx', import.meta.url))` so `process.cwd()` doesn't matter
+- Leaving `resourceMode` unset — the framework host-detects (`'inline'` for Claude, `'cdn'` for others)
+- Naming the widget `*.widget.tsx` so the scaffolded `tsconfig.json`'s `exclude` keeps it out of the server typecheck
+
+## Why these defaults matter
+
+- **`import.meta.url` anchoring** — relative paths in `FileSource` resolve against `process.cwd()`, not the tool file (#444). Running the server from a different directory breaks the widget at tool-call time. Anchoring fixes it once.
+- **`resourceMode` unset** — leave it. The framework picks `'inline'` for Claude (React bundled into the widget — actually renders) and `'cdn'` for everyone else (smaller payload via esm.sh). Setting it explicitly only locks in one behavior across all clients.
+- **`hydrate: false`** — default. React SSR output is static HTML; the bridge IIFE handles any interactivity. Enabling hydration creates React error #418 in Claude's iframe sandbox where the client-side render diverges from the SSR render.
+- **`*.widget.tsx` naming** — the scaffolded `tsconfig.json` excludes `**/*.widget.tsx` from the server typecheck (#445). The widget compiles via uipack/esbuild at render time with its own React-aware config.

package/catalog/create-tool/examples/24-tool-with-ui-csp-and-bridge.md

@@ -0,0 +1,127 @@
+---
+name: 24-tool-with-ui-csp-and-bridge
+level: advanced
+description: 'Interactive tool widget that fetches from an allow-listed CSP origin and invokes another tool via `window.FrontMcpBridge.callTool` — the full pattern for live-data widgets that need cross-tool composition.'
+tags: [ui, csp, widgetAccessible, FrontMcpBridge, interactive-widget]
+features:
+  - "Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)"
+  - 'Opting the widget into cross-tool calls with `widgetAccessible: true` and using `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs'
+  - "Embedding initial data into the widget's inline `<script>` safely via `ctx.helpers.jsonEmbed(...)` (escapes `</script>`)"
+  - 'Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback'
+---
+
+# Tool With Ui Csp And Bridge
+
+Interactive tool widget that fetches from an allow-listed CSP origin and invokes another tool via `window.FrontMcpBridge.callTool` — the full pattern for live-data widgets that need cross-tool composition.
+
+The advanced widget pattern. The tool's response renders a stock-quote card with a "Refresh" button that calls another tool through the bridge. CSP locks down outbound fetches; the bridge routes cross-tool calls to the right host adapter (OpenAI / Claude / direct) automatically.
+
+## Code
+
+```typescript
+// src/apps/main/tools/get-quote/get-quote.tool.ts
+import { PublicMcpError, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+const inputSchema = { symbol: z.string().regex(/^[A-Z]{1,5}$/) };
+const outputSchema = { symbol: z.string(), priceUsd: z.number(), asOf: z.string() };
+
+@Tool({
+  name: 'get_quote',
+  description: 'Get the latest stock price for a ticker symbol',
+  inputSchema,
+  outputSchema,
+})
+export class GetQuoteTool extends ToolContext {
+  async execute(input: { symbol: string }) {
+    const res = await this.fetch(`https://api.market.example/quote/${input.symbol}`);
+    if (!res.ok) {
+      this.fail(new PublicMcpError(`Quote upstream returned ${res.status} ${res.statusText}`));
+    }
+    const body = (await res.json()) as { price: number; ts: string };
+    return { symbol: input.symbol, priceUsd: body.price, asOf: body.ts };
+  }
+}
+```
+
+```typescript
+// src/apps/main/tools/show-quote/show-quote.tool.ts
+import { PublicMcpError, Tool, ToolContext, z, type TemplateContext } from '@frontmcp/sdk';
+
+const inputSchema = { symbol: z.string().regex(/^[A-Z]{1,5}$/) };
+const outputSchema = { symbol: z.string(), priceUsd: z.number(), asOf: z.string() };
+type In = { symbol: string };
+type Out = { symbol: string; priceUsd: number; asOf: string };
+
+@Tool({
+  name: 'show_quote',
+  description: 'Render a live quote widget for a ticker symbol',
+  inputSchema,
+  outputSchema,
+  ui: {
+    widgetDescription: 'Live stock quote with refresh',
+    widgetAccessible: true, // required for window.FrontMcpBridge.callTool
+    invocationStatus: { invoking: 'Fetching quote…', invoked: 'Quote loaded' },
+    csp: {
+      // CSP applies to the widget iframe — only allow fetches to our own market-data API.
+      // Framework emits this on the resource's _meta.ui.csp so Claude honors it (#455).
+      connectDomains: ['https://api.market.example'],
+    },
+    template: (ctx: TemplateContext<In, Out>) => {
+      const initial = ctx.helpers.jsonEmbed(ctx.output);
+      return `
+        <div style="padding:16px;font-family:system-ui">
+          <h2 style="margin:0">${ctx.helpers.escapeHtml(ctx.output.symbol)}</h2>
+          <p id="price" style="font-size:36px;margin:8px 0">$${ctx.output.priceUsd.toFixed(2)}</p>
+          <p id="asof" style="color:#666;margin:0">As of ${ctx.helpers.escapeHtml(ctx.output.asOf)}</p>
+          <button id="refresh" style="margin-top:12px;padding:8px 16px">Refresh</button>
+          <script>
+            (function () {
+              var current = ${initial};
+              var btn = document.getElementById('refresh');
+              btn.addEventListener('click', async function () {
+                btn.disabled = true;
+                btn.textContent = 'Refreshing…';
+                try {
+                  // FrontMcpBridge routes to OpenAI SDK / Claude postMessage / FrontMCP direct
+                  // automatically. NEVER call window.openai.* directly — it breaks cross-host.
+                  var next = await window.FrontMcpBridge.callTool('get_quote', { symbol: current.symbol });
+                  current = next;
+                  document.getElementById('price').textContent = '$' + next.priceUsd.toFixed(2);
+                  document.getElementById('asof').textContent = 'As of ' + next.asOf;
+                } finally {
+                  btn.disabled = false;
+                  btn.textContent = 'Refresh';
+                }
+              });
+            })();
+          </script>
+        </div>
+      `;
+    },
+  },
+})
+export class ShowQuoteTool extends ToolContext {
+  async execute(input: In): Promise<Out> {
+    const res = await this.fetch(`https://api.market.example/quote/${input.symbol}`);
+    if (!res.ok) {
+      this.fail(new PublicMcpError(`Quote upstream returned ${res.status} ${res.statusText}`));
+    }
+    const body = (await res.json()) as { price: number; ts: string };
+    return { symbol: input.symbol, priceUsd: body.price, asOf: body.ts };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)
+- Opting the widget into cross-tool calls with `widgetAccessible: true` and using `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs
+- Embedding initial data into the widget's inline `<script>` safely via `ctx.helpers.jsonEmbed(...)` (escapes `</script>`)
+- Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback
+
+## Why these choices
+
+- **`widgetAccessible: true`** — required for `window.FrontMcpBridge.callTool`. Without it, the bridge is read-only (the widget can read `getToolInput` / `getToolOutput` but can't invoke tools).
+- **`csp.connectDomains`** — limits what the widget can `fetch` to. Without a CSP, the host's default applies (which may block everything in Claude). With `connectDomains: ['https://api.market.example']`, only that origin is reachable.
+- **`window.FrontMcpBridge.callTool` not `window.openai.callTool`** — the bridge handles host detection. `window.openai.*` works on OpenAI Apps SDK but breaks everywhere else.
+- **`jsonEmbed` not `JSON.stringify`** — `JSON.stringify` doesn't escape `</script>` and can break out of the inline script tag. `jsonEmbed` does.

package/catalog/create-tool/examples/25-tool-handing-off-to-job.md

@@ -0,0 +1,143 @@
+---
+name: 25-tool-handing-off-to-job
+level: advanced
+description: 'Thin tool that validates input and enqueues a `@Job` to do the heavy lifting — the right pattern for any operation that takes more than a few seconds.'
+tags: [composition, jobs, job-handoff, hideFromDiscovery]
+features:
+  - 'Splitting a long-running operation into a thin tool (validates, enqueues, returns a tracking handle) plus a `@Job` (does the work)'
+  - Returning the job ID + status URL from the tool so the client can poll or stream updates
+  - "Using `availableWhen: { surface: ['mcp', 'agent'] }` on the tool while leaving the heavy `@Job` invisible to direct invocation"
+  - 'Why this beats running the heavy work inside `execute()` (avoids tool-call timeout limits, lets the job retry independently)'
+---
+
+# Tool Handing Off To Job
+
+Thin tool that validates input and enqueues a `@Job` to do the heavy lifting — the right pattern for any operation that takes more than a few seconds.
+
+Tools are for synchronous-ish interactions (≤30s end-to-end). Anything longer should run in a `@Job`, with a thin tool to kick it off.
+
+## Code
+
+```typescript
+// src/apps/main/jobs/export-data.job.ts
+import { Job, JobContext } from '@frontmcp/sdk';
+
+@Job({
+  name: 'export_data',
+  description: 'Export a dataset to CSV',
+  retry: { maxAttempts: 3, backoff: 'exponential' },
+})
+export class ExportDataJob extends JobContext {
+  async run(args: { datasetId: string; format: 'csv' | 'json' }) {
+    await this.progress(0, 100, 'Loading dataset…');
+    const rows = await this.loadDataset(args.datasetId);
+
+    await this.progress(50, 100, 'Serializing…');
+    const blob = await this.serialize(rows, args.format);
+
+    await this.progress(95, 100, 'Uploading…');
+    const downloadUrl = await this.upload(blob);
+
+    await this.progress(100, 100, 'Done');
+    return { downloadUrl, rowCount: rows.length };
+  }
+
+  private async loadDataset(_id: string) {
+    return [{ a: 1 }, { a: 2 }];
+  }
+  private async serialize(_rows: unknown[], _fmt: string) {
+    return Buffer.alloc(0);
+  }
+  private async upload(_blob: Buffer) {
+    return 'https://exports.example/x.csv';
+  }
+}
+```
+
+```typescript
+// src/apps/main/tools/export-data.tool.ts
+import { ResourceNotFoundError, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+import { DATASETS, JOBS } from '../tokens';
+
+const inputSchema = {
+  datasetId: z.string().uuid(),
+  format: z.enum(['csv', 'json']).default('csv'),
+};
+const outputSchema = {
+  jobId: z.string(),
+  statusUrl: z.string().url(),
+  estimatedSeconds: z.number().int(),
+};
+
+@Tool({
+  name: 'export_data',
+  description: 'Start a dataset export — returns a job handle the client can poll',
+  inputSchema,
+  outputSchema,
+  availableWhen: { surface: ['mcp', 'agent'] },
+  annotations: { idempotentHint: false, openWorldHint: false },
+})
+export class ExportDataTool extends ToolContext {
+  async execute(input: { datasetId: string; format: 'csv' | 'json' }) {
+    // 1. AUTHORIZE BEFORE ENQUEUEING. The job inherits this caller's auth scope at
+    //    enqueue time, so an unchecked tool here would let any caller export any
+    //    dataset they happen to know the ID of. Concretely: look up the dataset
+    //    scoped to the caller's tenant / user identity, fail fast if missing.
+    const datasets = this.get(DATASETS);
+    const userId = this.auth.user.sub;
+    const tenantId = this.auth.claims['tenantId'] as string | undefined;
+    const dataset = await datasets.findForUser(input.datasetId, { userId, tenantId });
+    if (!dataset) {
+      this.fail(new ResourceNotFoundError(`dataset:${input.datasetId}`));
+    }
+
+    // 2. Enqueue the job — runs in the caller's auth scope (the job's JobContext
+    //    re-checks tenant / user access inside `run()` as a defense-in-depth).
+    const jobs = this.get(JOBS);
+    const job = await jobs.enqueue('export_data', input, { userId, tenantId });
+
+    // 3. Return a handle the client can poll / stream.
+    return {
+      jobId: job.id,
+      statusUrl: `/jobs/${job.id}`,
+      estimatedSeconds: 30,
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+import { ExportDataJob } from './jobs/export-data.job';
+import { ExportDataTool } from './tools/export-data.tool';
+
+@App({
+  name: 'main',
+  tools: [ExportDataTool],
+  jobs: [ExportDataJob],
+})
+export class MainApp {}
+```
+
+## What This Demonstrates
+
+- Splitting a long-running operation into a thin tool (validates, enqueues, returns a tracking handle) plus a `@Job` (does the work)
+- Returning the job ID + status URL from the tool so the client can poll or stream updates
+- Using `availableWhen: { surface: ['mcp', 'agent'] }` on the tool while leaving the heavy `@Job` invisible to direct invocation
+- Why this beats running the heavy work inside `execute()` (avoids tool-call timeout limits, lets the job retry independently)
+
+## Why hand off
+
+| Inside `execute()`                              | Inside a `@Job`                                                                               |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Capped by the tool's `timeout` (typically ≤30s) | Designed for minutes / hours                                                                  |
+| One attempt — fails on transient errors         | Retry config — `maxAttempts`, `backoff`                                                       |
+| Progress emits to the current MCP session only  | Job runs independently of the session — can survive disconnects (with a persistent job store) |
+| Synchronous from the client's POV               | Asynchronous — client polls `statusUrl` or subscribes to a channel                            |
+
+If the work can take >10 seconds OR needs to survive a session drop OR needs retry-on-failure, it belongs in a job.
+
+See `create-job` for the full job surface — retry, progress, batching, permission scopes.

package/catalog/create-tool/examples/26-tool-with-resource-link-output.md

@@ -0,0 +1,94 @@
+---
+name: 26-tool-with-resource-link-output
+level: advanced
+description: "Tool returning `outputSchema: 'resource_link'` — the URI is sent to the client; the client fetches the body via `resources/read`. The right pattern for large or cacheable payloads."
+tags: [output-schema, resource_link, large-payload, caching]
+features:
+  - "Returning `outputSchema: 'resource_link'` from a tool — `{ type: 'resource_link', uri }`, body fetched separately"
+  - "Pairing the tool with a matching `@Resource({ uri: 'export://{exportId}.csv' })` URI template that resolves to the actual body"
+  - "When `'resource_link'` beats `'image'` / `'audio'` / a raw byte response (large payloads, cacheable URIs, deferred fetch)"
+  - 'Cross-linking to the `create-resource` skill for the URI-template resource on the other end'
+---
+
+# Tool With Resource Link Output
+
+Tool returning `outputSchema: 'resource_link'` — the URI is sent to the client; the client fetches the body via `resources/read`. The right pattern for large or cacheable payloads.
+
+When the tool's output is large (>1MB) or cacheable, return a `'resource_link'` instead of inlining the bytes. The tool returns just `{ uri }`; the client decides when to fetch the body via `resources/read`.
+
+## Code
+
+```typescript
+// src/apps/main/resources/export.resource.ts
+// (Lives in this app — see the create-resource skill for the full URI-template surface)
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+import { EXPORTS } from '../tokens';
+
+@Resource({
+  uri: 'export://{exportId}.csv',
+  description: 'Generated export CSV',
+})
+export class ExportCsvResource extends ResourceContext<{ exportId: string }> {
+  async read(params: { exportId: string }) {
+    const exports = this.get(EXPORTS);
+    const csv = await exports.loadCsv(params.exportId); // returns Buffer or stream
+    return {
+      contents: [{ uri: `export://${params.exportId}.csv`, mimeType: 'text/csv', blob: csv.toString('base64') }],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/tools/start-export.tool.ts
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+import { EXPORTS } from '../tokens';
+
+const inputSchema = {
+  datasetId: z.string().uuid(),
+};
+const outputSchema = 'resource_link';
+
+@Tool({
+  name: 'start_export',
+  description: 'Generate an export and return a resource link the client can read',
+  inputSchema,
+  outputSchema,
+  annotations: { idempotentHint: false },
+})
+export class StartExportTool extends ToolContext {
+  async execute(input: { datasetId: string }) {
+    const exports = this.get(EXPORTS);
+    const exportId = await exports.create(input.datasetId);
+
+    // Return the resource link — include the `type: 'resource_link'` discriminator
+    // (without it the content block is dropped). The client fetches the body via resources/read.
+    return { type: 'resource_link' as const, uri: `export://${exportId}.csv` };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Returning `outputSchema: 'resource_link'` from a tool — `{ type: 'resource_link', uri }`, body fetched separately
+- Pairing the tool with a matching `@Resource({ uri: 'export://{exportId}.csv' })` URI template that resolves to the actual body
+- When `'resource_link'` beats `'image'` / `'audio'` / a raw byte response (large payloads, cacheable URIs, deferred fetch)
+- Cross-linking to the `create-resource` skill for the URI-template resource on the other end
+
+## `'resource_link'` vs `'resource'` vs `'image'` / `'audio'`
+
+| Output                | When                                                                                                                        |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `'resource_link'`     | URI only. Best for large payloads (>1MB), cacheable content, deferred-fetch UX. Tool stays cheap; client fetches on demand. |
+| `'resource'`          | URI + inline content in one response. Best when the client always needs the body immediately (small-to-medium size).        |
+| `'image'` / `'audio'` | Inlined base64. Simplest for small media (≤1MB). No URI involved.                                                           |
+
+## Why split tool + resource
+
+- **Tool runs fast** — just generates the URI; doesn't materialize the whole payload in the response.
+- **Client caches by URI** — repeated requests for `export://abc.csv` hit the client's cache; the tool only runs again if the URI changes.
+- **Resource lifecycle is independent** — you can expire resources, regenerate them on demand, version them by URI suffix.
+
+See the `create-resource` skill for URI templates, parameter validation, multi-content reads, and binary vs text resources.

package/catalog/create-tool/examples/27-tool-with-examples-metadata.md

@@ -0,0 +1,90 @@
+---
+name: 27-tool-with-examples-metadata
+level: basic
+description: 'Tool with the `examples: [...]` field on `@Tool({...})` — concrete input (and optional expected output) examples consumed by the CodeCall `codecall:describe` tool to give agents accurate usage examples.'
+tags: [examples-metadata, codecall, describe]
+features:
+  - 'Adding `examples: [{ description, input, output? }]` to `@Tool({...})` so `codecall:describe` surfaces canned invocations'
+  - 'Writing realistic example inputs so the generated describe output is concrete, not abstract'
+  - 'Including `output?` for examples where showing the expected result helps an agent understand the tool'
+  - 'Why `examples` are advisory metadata — not emitted in `tools/list`, only consumed by `codecall:describe`'
+---
+
+# Tool With Examples Metadata
+
+Tool with the `examples: [...]` field on `@Tool({...})` — concrete input (and optional expected output) examples consumed by the CodeCall `codecall:describe` tool to give agents accurate usage examples.
+
+The `examples` field is purely advisory — the CodeCall `describe` tool uses it as the highest-priority source of usage examples (user-provided examples take precedence over auto-generated ones, up to 5). It is **not** emitted in the `tools/list` MCP response. Use it for any tool that benefits from concrete usage hints when CodeCall is enabled.
+
+## Code
+
+```typescript
+// src/apps/main/tools/convert-currency.tool.ts
+import { Tool, ToolContext, ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+const inputSchema = {
+  amount: z.number().positive(),
+  from: z.string().regex(/^[A-Z]{3}$/, 'ISO 4217 code, e.g. USD'),
+  to: z.string().regex(/^[A-Z]{3}$/),
+};
+const outputSchema = { converted: z.number(), rate: z.number(), asOf: z.string() };
+
+@Tool({
+  name: 'convert_currency',
+  description: 'Convert an amount from one currency to another',
+  inputSchema,
+  outputSchema,
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+  examples: [
+    {
+      description: 'Convert 100 USD to EUR',
+      input: { amount: 100, from: 'USD', to: 'EUR' },
+      output: { converted: 91.4, rate: 0.914, asOf: '2026-05-29T12:00:00Z' },
+    },
+    {
+      description: 'Convert 1,000,000 GBP to JPY',
+      input: { amount: 1_000_000, from: 'GBP', to: 'JPY' },
+    },
+    {
+      description: 'Convert 50 EUR to USD',
+      input: { amount: 50, from: 'EUR', to: 'USD' },
+    },
+  ],
+})
+export class ConvertCurrencyTool extends ToolContext {
+  async execute(
+    input: ToolInputOf<{ inputSchema: typeof inputSchema }>,
+  ): Promise<ToolOutputOf<{ outputSchema: typeof outputSchema }>> {
+    const rate = await this.fetchRate(input.from, input.to);
+    return { converted: +(input.amount * rate).toFixed(2), rate, asOf: new Date().toISOString() };
+  }
+
+  private async fetchRate(_from: string, _to: string): Promise<number> {
+    return 0.914;
+  }
+}
+```
+
+## What This Demonstrates
+
+- Adding `examples: [{ description, input, output? }]` to `@Tool({...})` so `codecall:describe` surfaces canned invocations
+- Writing realistic example inputs so the generated describe output is concrete, not abstract
+- Including `output?` for examples where showing the expected result helps an agent understand the tool
+- Why `examples` are advisory metadata — not emitted in `tools/list`, only consumed by `codecall:describe`
+
+## Where examples show up
+
+- **`codecall:describe`** — the CodeCall plugin's `describe` tool uses these as its top-priority source of usage examples (user-provided examples win over auto-generated ones, capped at 5). This is the one place `examples` is actually read.
+- **Not in `tools/list`** — the `tools/list` MCP response does not include `examples`; clients never see them there.
+
+## When to include `output?`
+
+- ✅ When showing the expected output makes the tool's purpose clearer at a glance.
+- ✅ When an agent benefits from seeing a representative result shape in the `codecall:describe` output before composing a call.
+- ❌ For tools where the output is highly variable / live data (e.g. `web_search` results). Just show the input.
+
+## Don't
+
+- Don't put sensitive example data — `examples` are surfaced verbatim to agents via `codecall:describe`. Use synthetic IDs (`u_1`), test addresses (`@example.com`), demo amounts.
+- Don't pad with low-value examples just to hit a count. 2–4 well-chosen examples beats 20 trivial ones.
+- Don't rely on `examples` for documentation — they're advisory hints, not formal docs. Put substantive guidance in `description`.

package/catalog/create-tool/references/annotations.md

@@ -0,0 +1,96 @@
+---
+name: annotations
+description: readOnlyHint, destructiveHint, idempotentHint, openWorldHint, title — behavioral hints for clients.
+---
+
+# `annotations`
+
+Optional behavioral hints on `@Tool({...})`. AI clients use them to decide whether to gate the call behind a confirmation dialog, parallelize calls, retry on failure, etc.
+
+```typescript
+@Tool({
+  name: 'delete_user',
+  description: 'Delete a user account',
+  inputSchema,
+  outputSchema,
+  annotations: {
+    title: 'Delete user',
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+})
+```
+
+## Fields
+
+| Field             | Type      | Default                             | Meaning                                                                        |
+| ----------------- | --------- | ----------------------------------- | ------------------------------------------------------------------------------ |
+| `title`           | `string`  | —                                   | Human-readable display name for client UIs (overrides `name` for presentation) |
+| `readOnlyHint`    | `boolean` | `false`                             | Tool only reads — no side effects. Safe to call freely.                        |
+| `destructiveHint` | `boolean` | `true` (when `readOnlyHint: false`) | Tool may delete or overwrite. Clients usually trigger a confirmation.          |
+| `idempotentHint`  | `boolean` | `false`                             | Repeated calls with same input produce the same result. Safe to retry.         |
+| `openWorldHint`   | `boolean` | `true`                              | Tool interacts with external services / network. `false` = local-only.         |
+
+## How clients use them
+
+| Annotation              | Common client behavior                                             |
+| ----------------------- | ------------------------------------------------------------------ |
+| `readOnlyHint: true`    | Tool may run in parallel with other reads; no confirmation needed  |
+| `destructiveHint: true` | Confirmation dialog before invocation; "are you sure?"             |
+| `idempotentHint: true`  | Auto-retry on transient failures                                   |
+| `openWorldHint: false`  | Hint that the tool is offline-safe                                 |
+| `title`                 | Shown in tool pickers and history instead of the snake_case `name` |
+
+## Common combinations
+
+```typescript
+// Read-only query tool — safe, retryable
+annotations: {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+}
+
+// Destructive admin action
+annotations: {
+  destructiveHint: true,
+  idempotentHint: true, // deleting twice still leaves the thing deleted
+  openWorldHint: false,
+}
+
+// Send an email
+annotations: {
+  readOnlyHint: false,
+  destructiveHint: false, // not destroying, just sending
+  idempotentHint: false,  // each call sends a new email
+  openWorldHint: true,
+}
+
+// External API search
+annotations: {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true,
+}
+```
+
+## Don't lie to the client
+
+Annotations are advisory but the client trusts them:
+
+- Don't set `readOnlyHint: true` on a tool that writes — clients may parallelize it.
+- Don't set `idempotentHint: true` on a tool that has incremental side effects — clients may retry and double up.
+- Don't omit `destructiveHint: true` on a delete — users may not get the confirmation they need.
+
+## When to omit annotations entirely
+
+For ambiguous or non-obvious cases, omit. The defaults (`readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true`) are the **conservative** assumption — clients will gate and not parallelize, which is the safe wrong choice if you're unsure.
+
+## See also
+
+- [`20-tool-with-annotations`](../examples/20-tool-with-annotations.md)
+- [`decorator-options.md`](./decorator-options.md)