@cyanheads/mcp-ts-core 0.8.1 → 0.8.3

package/dist/mcp-server/transports/http/landing-page/sections/tools.js

@@ -1,40 +1,73 @@
 /**
- * @fileoverview Tools section — responsive 2-column card grid, optionally
- * prefix-grouped when ≥2 tools share a common `snake_case` prefix. Each card
- * carries annotation pills (read-only / destructive / open-world / task /
- * app), auth scope chips, a JSON-RPC invocation snippet, and a collapsible
- * input-schema preview.
+ * @fileoverview Tools section — responsive card grid grouped by safety
+ * mutability (read / write / destructive). Each card carries annotation
+ * pills, a scope chip, a JSON-RPC invocation snippet, and a collapsible
+ * input-schema preview. A filter bar above the grid wires chip + search
+ * filtering through `data-mutability` / `data-name` attributes consumed
+ * by the inline filter script.
  *
  * @module src/mcp-server/transports/http/landing-page/sections/tools
  */
 import { html } from '../../../../../utils/formatting/html.js';
 import { renderPill, renderSectionHeading, renderSnippet } from '../primitives.js';
+/**
+ * Mutability bucket order — safe defaults first, deliberate engagement last.
+ * Filter chips render in this order too.
+ */
+const MUTABILITY_ORDER = ['read', 'write', 'destructive'];
 export function renderToolsSection(tools) {
     if (tools.length === 0)
         return html ``;
-    const groups = groupToolsByPrefix(tools);
-    // A single group — whether labeled or not — would render as redundant with
-    // the section header. Skip the sub-heading; render a flat grid.
-    const showHeadings = groups.length > 1;
-    const body = groups.map((group) => {
-        const heading = showHeadings && group.label ? html `<h4 class="group-heading">${group.label}</h4>` : html ``;
-        return html `${heading}<div class="card-grid">${group.tools.map(renderToolCard)}</div>`;
+    const buckets = bucketByMutability(tools);
+    const populatedBuckets = MUTABILITY_ORDER.filter((m) => buckets[m].length > 0);
+    // A single bucket is redundant with the section header — skip per-group
+    // labels in that case but keep `data-mutability` on cards so the filter
+    // chips still work.
+    const showHeadings = populatedBuckets.length > 1;
+    const groups = populatedBuckets.map((mutability) => {
+        const bucketTools = buckets[mutability];
+        const heading = showHeadings
+            ? html `<h4 class="group-heading" data-group="${mutability}">${mutability} <span class="group-count">${String(bucketTools.length)}</span></h4>`
+            : html ``;
+        return html `${heading}<div class="card-grid" data-grid="${mutability}">${bucketTools.map((t) => renderToolCard(t, mutability))}</div>`;
     });
     return html `
-    <section aria-labelledby="section-tools">
+    <section aria-labelledby="section-tools" data-tools-section>
       ${renderSectionHeading('section-tools', 'Tools', tools.length)}
-      ${body}
+      ${renderToolFilterBar(populatedBuckets)}
+      <div class="tools-body">${groups}</div>
+      <p class="tools-empty" hidden>No tools match the current filter.</p>
     </section>
   `;
 }
-function renderToolCard(tool) {
+function renderToolFilterBar(populatedBuckets) {
+    const chips = [
+        html `<button type="button" class="tool-chip" data-filter-mutability="all" aria-pressed="true">all</button>`,
+    ];
+    for (const m of populatedBuckets) {
+        chips.push(html `<button type="button" class="tool-chip tool-chip--${m}" data-filter-mutability="${m}" aria-pressed="false">${m}</button>`);
+    }
+    return html `
+    <div class="tool-filter-bar" role="search" aria-label="Filter tools">
+      <div class="tool-chips" role="group" aria-label="Filter by mutability">${chips}</div>
+      <label class="tool-search">
+        <span class="visually-hidden">Search tools</span>
+        <input
+          type="search"
+          data-tool-search
+          placeholder="Search tools…"
+          autocomplete="off"
+          spellcheck="false"
+        />
+      </label>
+    </div>
+  `;
+}
+function renderToolCard(tool, mutability) {
     const anchor = `tool-${tool.name}`;
     const annotations = tool.annotations;
-    const pills = [];
-    if (annotations?.readOnlyHint)
-        pills.push(renderPill('read-only', 'readonly'));
-    if (annotations?.destructiveHint === true)
-        pills.push(renderPill('destructive', 'destructive'));
+    // Mutability badge first — the safety signal readers track at a glance.
+    const pills = [renderPill(mutability, mutability)];
     if (annotations?.openWorldHint)
         pills.push(renderPill('open-world', 'openworld'));
     if (tool.isTask)
@@ -42,75 +75,87 @@ function renderToolCard(tool) {
     if (tool.isApp)
         pills.push(renderPill('app', 'app'));
     const source = tool.sourceUrl
-        ? html `<a class="source-link" href="${tool.sourceUrl}" rel="noopener">view source ↗</a>`
+        ? html `<a class="source-link" href="${tool.sourceUrl}" rel="noopener" aria-label="View source for ${tool.name}">view source ↗</a>`
+        : html ``;
+    const scopeChips = tool.auth && tool.auth.length > 0
+        ? html `<span class="card-scope" title="${tool.auth.join(', ')}"><span class="card-meta-label">scope</span>${tool.auth.map((scope) => html ` <code class="scope-chip">${scopeAccessLevel(scope)}</code>`)}</span>`
         : html ``;
     const schemaPreview = tool.inputSchema
         ? html `
-        <details>
-          <summary>Input schema</summary>
+        <details class="card-detail">
+          <summary>schema</summary>
           <pre><code>${JSON.stringify(tool.inputSchema, null, 2)}</code></pre>
         </details>
       `
         : html ``;
     const invocation = html `
-    <details>
-      <summary>Invocation</summary>
+    <details class="card-detail">
+      <summary>invocation</summary>
       ${renderSnippet(`tool-${tool.name}`, buildInvocationSnippet(tool))}
     </details>
   `;
-    const authBadges = tool.auth && tool.auth.length > 0
-        ? html `<div class="card-meta"><span class="card-meta-label">scopes</span>${tool.auth.map((scope) => html ` <span class="pill pill-auth">${scope}</span>`)}</div>`
-        : html ``;
+    // Search target: name + description as a single lowercase string. Hidden
+    // attribute (not visible) so the filter script can match without parsing
+    // DOM text repeatedly. Description gets normalized whitespace so multi-line
+    // entries don't waste haystack length.
+    const searchTarget = `${tool.name} ${tool.description}`.replace(/\s+/g, ' ').toLowerCase();
     return html `
-    <article class="card" id="${anchor}">
-      <div class="card-head">
+    <article
+      class="card tool-card"
+      id="${anchor}"
+      data-tool-card
+      data-mutability="${mutability}"
+      data-name="${tool.name}"
+      data-search="${searchTarget}"
+    >
+      <header class="card-head">
         <h3 class="card-title"><a href="#${anchor}">${tool.name}</a></h3>
         <div class="pill-row" role="list">${pills}</div>
         ${source}
-      </div>
+      </header>
       <p class="card-desc">${tool.description}</p>
-      ${authBadges}
-      ${invocation}
-      ${schemaPreview}
+      <footer class="card-foot">
+        ${scopeChips}
+        <div class="card-actions">
+          ${invocation}
+          ${schemaPreview}
+        </div>
+      </footer>
     </article>
   `;
 }
-function groupToolsByPrefix(tools) {
-    if (tools.length < 3)
-        return [{ label: null, tools }];
-    const prefixCounts = new Map();
-    for (const tool of tools) {
-        const prefix = tool.name.split('_', 1)[0];
-        if (!prefix)
-            continue;
-        prefixCounts.set(prefix, (prefixCounts.get(prefix) ?? 0) + 1);
-    }
-    const groupablePrefixes = new Set([...prefixCounts.entries()].filter(([, count]) => count >= 2).map(([p]) => p));
-    if (groupablePrefixes.size === 0)
-        return [{ label: null, tools }];
-    const groups = new Map();
-    const other = [];
-    for (const tool of tools) {
-        const prefix = tool.name.split('_', 1)[0];
-        if (prefix && groupablePrefixes.has(prefix)) {
-            const list = groups.get(prefix) ?? [];
-            list.push(tool);
-            groups.set(prefix, list);
-        }
-        else {
-            other.push(tool);
-        }
-    }
-    const out = [];
-    for (const [prefix, list] of groups) {
-        out.push({ label: titleCase(prefix), tools: list });
-    }
-    if (other.length > 0)
-        out.push({ label: 'Other', tools: other });
-    return out;
+/**
+ * Map a tool to a mutability bucket using its annotations. The MCP spec
+ * defaults `destructiveHint` to `true`, but treating annotation-less tools
+ * as "destructive" surprises readers — bucket as `write` unless the
+ * destructive hint is explicitly set. Mirrors how the annotation pills
+ * render today (`pill-destructive` requires `=== true`).
+ */
+function classifyMutability(tool) {
+    const a = tool.annotations;
+    if (a?.readOnlyHint === true)
+        return 'read';
+    if (a?.destructiveHint === true)
+        return 'destructive';
+    return 'write';
+}
+function bucketByMutability(tools) {
+    const buckets = { read: [], write: [], destructive: [] };
+    for (const tool of tools)
+        buckets[classifyMutability(tool)].push(tool);
+    return buckets;
 }
-function titleCase(s) {
-    return s.charAt(0).toUpperCase() + s.slice(1);
+/**
+ * Reduce a colon-delimited scope (`tool:foo:read`) to its trailing access
+ * level (`read`). Scopes that don't match the convention render verbatim —
+ * the linter doesn't enforce shape, so falling back is friendlier than
+ * eating the value.
+ */
+function scopeAccessLevel(scope) {
+    const idx = scope.lastIndexOf(':');
+    if (idx < 0 || idx === scope.length - 1)
+        return scope;
+    return scope.slice(idx + 1);
 }
 function buildInvocationSnippet(tool) {
     const args = {};

package/dist/mcp-server/transports/http/landing-page/sections/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../../../../src/mcp-server/transports/http/landing-page/sections/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../../../../src/mcp-server/transports/http/landing-page/sections/tools.ts"],"names":[],"mappings":"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"}

package/dist/types-global/errors.d.ts

@@ -116,13 +116,9 @@ export type ErrorResponse = z.infer<typeof ErrorSchema>;
  * Lets a definition advertise what it can fail with — the JSON-RPC code, a
  * stable machine-readable `reason`, and a human-readable `when` description.
  *
- * **Where it shows up:**
- * - Surfaced in `tools/list` / `resources/list` under
- *   `_meta['mcp-ts-core/errors']`, so MCP clients and agents can preview failure
- *   modes alongside the input/output schema.
- * - Validated by the startup linter — invalid codes, duplicate `reason` strings
- *   within a single definition, and (with the conformance check enabled)
- *   handler bodies that throw codes not in the contract are flagged.
+ * **Validation.** Checked by the startup linter — invalid codes, duplicate
+ * `reason` strings within a single definition, and (with the conformance check
+ * enabled) handler bodies that throw codes not in the contract are flagged.
  *
  * **Authoring guidance:**
  * - Keep `reason` short, snake_case, stable. Treat it like a CSS class name
@@ -171,19 +167,4 @@ export interface ErrorContract {
      */
     when: string;
 }
-/**
- * The MCP `_meta` namespace key under which `errors[]` is published in
- * `tools/list` and `resources/list`. Namespaced to avoid collisions with
- * other framework or vendor extensions.
- */
-export declare const ERROR_CONTRACT_META_KEY = "mcp-ts-core/errors";
-/**
- * Merges a tool/resource's `errors[]` contract into its `_meta` object under
- * {@link ERROR_CONTRACT_META_KEY}. Returns `undefined` when both sides are
- * absent so callers can spread conditionally without producing an empty
- * `_meta` field. Used by the tool and resource registries.
- *
- * @internal
- */
-export declare function buildMetaWithErrorContract(baseMeta: Record<string, unknown> | undefined, errors: readonly unknown[] | undefined): Record<string, unknown> | undefined;
 //# sourceMappingURL=errors.d.ts.map

package/dist/types-global/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"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"}

package/dist/types-global/errors.js

@@ -138,23 +138,4 @@ export const ErrorSchema = z
         .describe('Optional structured data providing more context about the error'),
 })
     .describe('Schema for validating structured error objects, ensuring consistency in error reporting.');
-/**
- * The MCP `_meta` namespace key under which `errors[]` is published in
- * `tools/list` and `resources/list`. Namespaced to avoid collisions with
- * other framework or vendor extensions.
- */
-export const ERROR_CONTRACT_META_KEY = 'mcp-ts-core/errors';
-/**
- * Merges a tool/resource's `errors[]` contract into its `_meta` object under
- * {@link ERROR_CONTRACT_META_KEY}. Returns `undefined` when both sides are
- * absent so callers can spread conditionally without producing an empty
- * `_meta` field. Used by the tool and resource registries.
- *
- * @internal
- */
-export function buildMetaWithErrorContract(baseMeta, errors) {
-    if (!errors || errors.length === 0)
-        return baseMeta;
-    return { ...(baseMeta ?? {}), [ERROR_CONTRACT_META_KEY]: errors };
-}
 //# sourceMappingURL=errors.js.map

package/dist/types-global/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",

package/skills/add-app-tool/SKILL.md

@@ -108,8 +108,10 @@ const APP_HTML = `<!DOCTYPE html>
   <!-- your UI markup -->
 
   <script type="module">
-    // Prefer a bundled or inlined SDK for the final shipped HTML. Leaving a live
-    // CDN import in the served ui:// resource is not the recommended default.
+    // PROTOTYPING ONLY — replace before shipping. Bundle via Vite +
+    // vite-plugin-singlefile or inline the SDK. Live CDN imports require
+    // CSP whitelisting, add supply-chain risk, and break offline use.
+    // See UI Notes below.
     import {
       App,
       applyDocumentTheme,
@@ -186,13 +188,27 @@ export const {{RESOURCE_EXPORT}} = appResource('ui://{{tool-name}}/app.html', {
 });
 ```
 
-## UI Design Notes
+## UI Notes
 
-- **Bundling:** Prefer Vite + `vite-plugin-singlefile` for any UI that uses `@modelcontextprotocol/ext-apps`. The served `ui://` HTML should ideally be self-contained. The inline template literal pattern is fine for zero-dependency UIs or when you inline the SDK yourself.
-- **Client-side SDK:** Author against `@modelcontextprotocol/ext-apps`, but ship a bundled or inlined artifact when possible. Avoid relying on a live CDN import as the default final pattern for portable host compatibility.
-- **CSP:** MCP Apps iframes run under deny-by-default CSP. With `appResource()`, put `_meta.ui.csp.resourceDomains` on the definition and the builder will mirror it into returned `resources/read` content items. With plain `resource()`, you still need to attach `_meta.ui` yourself in `format()`.
-- **App resource `format()`:** `appResource()` already preserves raw HTML for the default app MIME type and mirrors definition `_meta.ui` into content items. Add a custom `format()` only when you need extra per-read metadata or non-default content shaping.
-- **format() for app tools:** The first `text` content block is typically JSON that the UI parses via `ontoolresult`. Additional blocks provide a human-readable fallback that non-app hosts and LLMs consume. Do not rely on the JSON block alone for model-visible detail; the fallback blocks still need to render the fields the LLM must reason about.
+- **Ship self-contained HTML.** Author with Vite + `vite-plugin-singlefile` or inline the SDK. Live CDN imports in a `ui://` resource are a CSP footgun (every domain has to be whitelisted on `_meta.ui.csp.resourceDomains`), a supply-chain footgun (third-party JS executes inside the host's iframe), and a runtime footgun (every render needs network). The `unpkg` line in the template is for prototyping only.
+- **CSP.** MCP Apps iframes run under deny-by-default CSP. With `appResource()`, put `_meta.ui.csp.resourceDomains` on the definition; the builder mirrors it into returned `resources/read` content items. With plain `resource()`, attach `_meta.ui` yourself in `format()`.
+- **Adopt the host's visual identity, don't impose your own.** App UIs render inside the host's iframe alongside its native UI. Three host hooks layer on top of your CSS:
+  - `applyDocumentTheme(hostContext.theme)` — sets `color-scheme` and a `data-theme` attribute on `<html>`
+  - `applyHostStyleVariables(hostContext.styles.variables)` — installs host CSS custom properties on `:root` (host decides the names, e.g. `--mcp-color-bg-primary`)
+  - `applyHostFonts(hostContext.styles.css.fonts)` — installs `@font-face` rules for the host's font stack
+
+  Author CSS to *consume* these via `var(--mcp-color-bg-primary, /* fallback */ #fff)`. Don't hardcode brand colors that fight the host.
+- **Pre-connect baseline.** `app.connect()` is async — host context arrives a frame or two after first paint. Without a baseline, the UI flashes unstyled or wrong-themed on light hosts. Ship a `prefers-color-scheme`-aware default so the first frame is sensible:
+
+  ```css
+  :root { color-scheme: light dark; --bg: #fff; --fg: #111; }
+  @media (prefers-color-scheme: dark) { :root { --bg: #0c0d12; --fg: #ededef; } }
+  body { background: var(--bg); color: var(--fg); }
+  ```
+
+  Host vars override these once `onhostcontextchanged` fires.
+- **`format()` for app tools.** The first `text` content block is typically JSON that the UI parses via `ontoolresult`. Additional blocks are the human-readable fallback that non-app hosts and LLMs consume — they must render every field the LLM needs to reason about. JSON-only payloads leave model-visible context blind.
+- **App resource `format()`.** `appResource()` already preserves raw HTML for the default app MIME type and mirrors definition `_meta.ui` into content items. Add a custom `format()` only when you need extra per-read metadata or non-default content shaping.
 
 ## Registration
 

package/skills/add-resource/SKILL.md

@@ -109,7 +109,7 @@ If the repo already uses `src/mcp-server/resources/definitions/index.ts`, update
 
 ### Optional: declarative `errors[]` contract
 
-Resources can opt into the same typed error contract as tools — surfaced in `resources/list` under `_meta['mcp-ts-core/errors']` and bound to a typed `ctx.fail(reason, …)` keyed by the declared reason union:
+Resources can opt into the same typed error contract as tools — bound to a typed `ctx.fail(reason, …)` keyed by the declared reason union:
 
 ```typescript
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

package/skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "1.9"
+  version: "2.0"
   audience: external
   type: reference
 ---
@@ -44,6 +44,7 @@ For shape selection (Workflow or Instruction variants — standard single-action
  */
 
 import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 
 export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
   title: '{{TOOL_TITLE}}',
@@ -58,17 +59,25 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
     // All fields need .describe(). Only JSON-Schema-serializable Zod types allowed.
   }),
   // auth: ['tool:{{tool_name}}:read'],
-  // errors: [
-  //   { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No items matched the query.' },
-  //   { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited, when: 'Local queue at capacity.', retryable: true },
-  // ],
+
+  // Each entry declares a domain-specific failure mode and types
+  // `ctx.fail(reason, …)` against the declared union. Baseline codes
+  // (InternalError, ServiceUnavailable, Timeout, ValidationError,
+  // SerializationError) bubble freely — only declare domain-specific reasons.
+  // Delete this block if no domain failures apply.
+  errors: [
+    { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No items matched the query.' },
+    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited, when: 'Local queue at capacity.', retryable: true },
+  ],
 
   async handler(input, ctx) {
     ctx.log.info('Processing', { /* relevant input fields */ });
     // Pure logic — throw on failure, no try/catch.
     // With an `errors[]` contract: `throw ctx.fail('reason_id', message?, data?)`.
     // Without: throw via factories (`notFound`, `validationError`, …) or plain `Error`.
-    return { /* output */ };
+    const items = await search(input);
+    if (items.length === 0) throw ctx.fail('no_match', `No items matched "${input.query}"`);
+    return { items };
   },
 
   // format() populates MCP content[] — the markdown twin of structuredContent.
@@ -186,18 +195,38 @@ Single-item tools don't need this — they either succeed or throw. The partial
 
 ### Empty results need context
 
-An empty array with no explanation is a dead end. Echo back the criteria that produced zero results and, where possible, suggest how to broaden the search.
+An empty array with no explanation is a dead end. Echo back the criteria that produced zero results and, where possible, suggest how to broaden the search. The recovery hint needs three pieces working together — schema entry, handler return, and `format()` rendering — or the `format-parity` lint will flag the missing field.
 
 ```typescript
-// In handler — after getting zero results:
-if (results.length === 0) {
-  return {
-    items: [],
-    totalCount: 0,
-    message: `No items matched status="${input.status}" in project "${input.project}". `
-      + `Try a broader status filter or verify the project name.`,
-  };
-}
+// 1. Output schema — declare the recovery field so the linter sees it
+output: z.object({
+  items: z.array(ItemSchema).describe('Matching items.'),
+  totalCount: z.number().describe('Total matches before pagination.'),
+  message: z.string().optional()
+    .describe('Recovery hint when results are empty — echoes filters and suggests how to broaden. Absent on successful result pages.'),
+}),
+
+// 2. Handler — populate `message` when the result is empty
+async handler(input, ctx) {
+  const results = await search(input);
+  if (results.length === 0) {
+    return {
+      items: [],
+      totalCount: 0,
+      message: `No items matched status="${input.status}" in project "${input.project}". `
+        + `Try a broader status filter or verify the project name.`,
+    };
+  }
+  return { items: results, totalCount: results.length };
+},
+
+// 3. format() — render the recovery hint so content[]-only clients see it too
+format: (result) => {
+  const lines = [`**Total:** ${result.totalCount}`];
+  if (result.message) lines.push(`\n> ${result.message}`);
+  for (const item of result.items) lines.push(`- ${item.name}`);
+  return [{ type: 'text', text: lines.join('\n') }];
+},
 ```
 
 ### Sparse upstream data must stay honest
@@ -265,13 +294,51 @@ export const fetchArticles = tool('fetch_articles', {
 });
 ```
 
-**Baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring. Omit the contract only for throwaway prototypes — declare it everywhere else. Wire-level behavior is identical when omitted, but you lose the type-checked `ctx.fail`, the `tools/list` advertisement, and conformance lint coverage.
+**Baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring. Wire-level behavior is identical when the contract is omitted, but you lose the type-checked `ctx.fail`, the `tools/list` advertisement, and conformance lint coverage — declare a contract whenever the tool has a domain-specific failure mode.
 
 `ctx.fail` accepts an optional 4th `options` argument for ES2022 cause chaining: `throw ctx.fail('upstream_error', 'Upstream returned 500', { url }, { cause: e })`.
 
-**Service-thrown contract reasons.** When the throw happens in a called service rather than the handler itself, `ctx.fail` isn't reachable — services don't have `ctx`. Pass `data: { reason: 'X' }` to the factory in the service; the framework's auto-classifier preserves `data` on the wire, so the contract reason rides through unchanged. The handler bubbles the error without catching. See `add-service` for the pattern.
+#### Service-layer throws
+
+API-wrapping tools usually delegate to a service: `const data = await ncbi.fetch(input)`. The throw lives in the service, not the handler — and services don't receive `ctx`, so `ctx.fail` is unreachable from there. The fix is to pass `data: { reason: 'X' }` to the factory in the service. The framework's auto-classifier preserves `data` on the wire, so clients see the same `error.data.reason` they would have seen from `ctx.fail`. The handler doesn't catch — it just bubbles.
+
+The contract entry on the tool and the `data: { reason }` on the service throw need to use the **same reason string** so the two sides line up.
+
+```typescript
+// service — passes data.reason to match the consuming tool's contract
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+
+export class NcbiService {
+  async fetch(pmids: string[]) {
+    const response = await fetchWithRetry(...);
+    if (!response.ok) {
+      throw serviceUnavailable(
+        `NCBI returned HTTP ${response.status}`,
+        { reason: 'ncbi_unreachable', status: response.status },  // ← matches contract entry
+        { cause: undefined },
+      );
+    }
+    return response.json();
+  }
+}
+
+// tool — declares the matching contract entry, calls the service, doesn't catch
+export const fetchArticles = tool('fetch_articles', {
+  errors: [
+    { reason: 'ncbi_unreachable', code: JsonRpcErrorCode.ServiceUnavailable,
+      when: 'NCBI E-utilities is unreachable.', retryable: true },
+  ],
+  async handler(input, ctx) {
+    return { articles: await ncbi.fetch(input.pmids) };  // throws bubble unchanged
+  },
+});
+```
+
+See `add-service` for the full pattern.
+
+#### Ad-hoc factory throws (fallback)
 
-**Fallback: error factories.** Use when no contract entry fits — ad-hoc throws, prototype tools, or service-layer code. The framework also auto-classifies plain `throw new Error()` from message patterns as a last resort.
+When no contract entry fits — prototype code, one-off throws, or service-layer fallbacks — use error factories or plain `throw new Error()`. The framework auto-classifies plain `Error` from message patterns as a last resort.
 
 ```typescript
 // Client input error — agent can fix and retry
@@ -365,7 +432,7 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 - [ ] `format()` renders every field in the output schema — enforced at lint time via sentinel injection, startup fails with `format-parity` errors otherwise. Different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data. Primary fix: render the missing field in `format()` (use `z.discriminatedUnion` for list/detail variants). Escape hatch: if the output schema was over-typed for a genuinely dynamic upstream API, relax it (`z.object({}).passthrough()`) rather than maintaining aspirational typing
 - [ ] If wrapping external API: output schema and `format()` preserve uncertainty from sparse upstream payloads instead of inventing concrete values
 - [ ] `auth` scopes declared if the tool needs authorization
-- [ ] `errors: [...]` contract declared for known domain failure modes (recommended; omit only for throwaway prototypes)
+- [ ] `errors: [...]` contract declared for the tool's domain-specific failure modes — or block deleted if no domain failures apply (baseline codes bubble freely)
 - [ ] `task: true` added if the tool is long-running
 - [ ] Registered in the project's existing `createApp()` tool list (directly or via barrel)
 - [ ] `bun run devcheck` passes