@ultimat3/mcp 24.0.0 → 25.1.0

package/src/meta-surface.ts

@@ -268,40 +268,82 @@ export function schemaOf(tool: AnyMcpTool): JsonSchema {
  * every quote — a staff catalog measured 32.5k characters — and `JSON.parse` was never its reader's
  * job: the model's is. Same facts, same order; `describe_resource` stays JSON because a schema is.
  *
+ * Every per-action tag costs once per action, so each is stated where it is cheapest and still
+ * exact (#590): a scope shared by every action of the resource — or of one kind — is said once on
+ * the resource line (`hoistScopes`); only `action` is tagged, because untagged means `query` and
+ * the header says so. The kind comes from `destructive` (`headOf`), never from the name.
+ *
  * ```text
- * cases — Court cases of the account.
- *   listCases (query) {radicado?: string} — List the account's cases.
- *   closeCase (action; confirms; scope cases:write) {id: string} — Close a case.
+ * cases (scope cases) — Court cases of the account.
+ *   listCases {radicado?: string} — List the account's cases.
+ *   closeCase (action; confirms) {id: string} — Close a case.
  * ```
  */
 export function renderCatalog(resources: readonly MetaResource[]): string {
   if (resources.length === 0) return 'No resources are available to this caller.';
   const lines = [
-    `${resources.length} resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas.`,
+    `${resources.length} resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas. Untagged = read-only query; (action) may write; (confirms) waits for a human; … = more in describe_resource.`,
   ];
   for (const resource of resources) {
-    lines.push('', `${resource.name} — ${oneLine(resource.description)}`);
+    const hoisted = hoistScopes(resource.actions);
+    const said = hoisted.line === '' ? '' : ` (${hoisted.line})`;
+    lines.push('', `${resource.name}${said} — ${oneLine(resource.description)}`);
     for (const action of resource.actions) {
       const tags = [
-        action.kind,
+        ...(action.kind === 'action' ? ['action'] : []),
         ...(action.confirms === true ? ['confirms'] : []),
-        ...(action.scope === undefined ? [] : [`scope ${action.scope}`]),
-      ].join('; ');
-      lines.push(`  ${action.name} (${tags}) {${action.params}} — ${oneLine(action.description)}`);
+        ...(action.scope === undefined || hoisted.kinds.has(action.kind)
+          ? []
+          : [`scope ${action.scope}`]),
+      ];
+      const tagged = tags.length === 0 ? '' : ` (${tags.join('; ')})`;
+      lines.push(`  ${action.name}${tagged} {${action.params}} — ${oneLine(action.description)}`);
     }
   }
   return lines.join('\n');
 }
 
+/**
+ * The scopes said once on the resource line, and the kinds whose actions no longer repeat theirs.
+ * One scope for every action → `scope cases`. Otherwise per kind, because a token split into
+ * `cases:read` / `cases:write` is the common shape: `query scope cases:read; action scope
+ * cases:write`. A kind is hoisted only when EVERY action of it carries the SAME scope — one
+ * unscoped action among scoped ones must not inherit a gate the registry does not enforce.
+ * Computed over what THIS caller sees: the catalog is per caller.
+ */
+function hoistScopes(actions: readonly MetaAction[]): {
+  readonly line: string;
+  readonly kinds: ReadonlySet<MetaAction['kind']>;
+} {
+  const all = sharedScope(actions);
+  if (all !== undefined) return { line: `scope ${all}`, kinds: new Set(['query', 'action']) };
+  const parts: string[] = [];
+  const kinds = new Set<MetaAction['kind']>();
+  for (const kind of ['query', 'action'] as const) {
+    const scope = sharedScope(actions.filter((action) => action.kind === kind));
+    if (scope === undefined) continue;
+    parts.push(`${kind} scope ${scope}`);
+    kinds.add(kind);
+  }
+  return { line: parts.join('; '), kinds };
+}
+
+/** The scope every action carries, or `undefined` when there is none, one lacks it or two differ. */
+function sharedScope(actions: readonly MetaAction[]): string | undefined {
+  const first = actions[0]?.scope;
+  if (first === undefined) return undefined;
+  return actions.every((action) => action.scope === first) ? first : undefined;
+}
+
 /** A description authored across lines is still one catalog line. */
 const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim();
 
 function headOf(tool: AnyMcpTool): Omit<MetaAction, 'params'> {
   return {
     name: tool.name,
-    // `=== true`, as `ToolRegistry.verbClass` meters it: an omitted `destructive` is a read in the
-    // rate limiter, so listing it as an action gave one tool two answers.
-    kind: tool.destructive === true ? 'action' : 'query',
+    // `=== false`, as `ToolRegistry.verbClass` meters it — one answer per tool. An omitted flag is
+    // an action: the header's "untagged = read-only query" holds only for a DECLARED read.
+    kind: tool.destructive === false ? 'query' : 'action',
     description: tool.description,
     ...(tool.confirms === true ? { confirms: true } : {}),
     ...(tool.scope === undefined ? {} : { scope: tool.scope }),
@@ -312,27 +354,44 @@ function sorted<V>(map: ReadonlyMap<string, V>): readonly [string, V][] {
   return [...map.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
-/** Past this, the hint says "see describe_resource" instead of pretending to be complete. */
-const HINT_MAX = 240;
+/** Fields a hint names before `…` — every required one is named regardless. */
+const HINT_FIELDS = 4;
+/** Optional fields stop being added once the hint is this long; required ones never stop. */
+const HINT_MAX = 100;
+/** Literals an enum hint names before `|…`. */
+const HINT_LITERALS = 8;
 
 /**
  * `name: type` per property, `?` when optional, an enum as its literals — the hint
  * `list_resources` carries so a common call needs no `describe_resource` round-trip.
+ *
+ * Cut by FIELDS, never by characters (#590): a character cut sliced `limit?: integer` into
+ * `limit?: i…`. Every required field is named, in declared order, because a call without one
+ * fails; optional fields follow until `HINT_FIELDS` names or `HINT_MAX` characters, and a trailing
+ * `…` says some were left out. `describe_resource` always has the full schema.
  */
 export function oneLineParams(schema: JsonSchema): string {
   const required = new Set(schema.required ?? []);
-  const parts = Object.entries(schema.properties ?? {}).map(
-    ([key, child]) => `${key}${required.has(key) ? '' : '?'}: ${typeHint(child)}`,
-  );
-  const line = parts.join(', ');
-  if (line.length <= HINT_MAX) return line;
-  return `${line.slice(0, HINT_MAX - 1)}… (describe_resource has the rest)`;
+  const fields = Object.entries(schema.properties ?? {}).map(([key, child]) => ({
+    required: required.has(key),
+    text: `${key}${required.has(key) ? '' : '?'}: ${typeHint(child)}`,
+  }));
+  const named = new Set(fields.filter((field) => field.required));
+  let length = [...named].reduce((sum, field) => sum + field.text.length + 2, 0);
+  for (const field of fields) {
+    if (field.required) continue;
+    if (named.size >= HINT_FIELDS || length + field.text.length > HINT_MAX) break;
+    named.add(field);
+    length += field.text.length + 2;
+  }
+  const parts = fields.filter((field) => named.has(field)).map((field) => field.text);
+  return named.size < fields.length ? [...parts, '…'].join(', ') : parts.join(', ');
 }
 
 function typeHint(schema: JsonSchema): string {
-  if (schema.enum !== undefined) return schema.enum.map((v) => JSON.stringify(v)).join('|');
+  if (schema.enum !== undefined) return literals(schema.enum.map((v) => JSON.stringify(v)));
   if (schema.const !== undefined) return JSON.stringify(schema.const);
-  if (schema.anyOf !== undefined) return schema.anyOf.map(typeHint).join('|');
+  if (schema.anyOf !== undefined) return literals(schema.anyOf.map(typeHint));
   if (schema.type === 'array') {
     if (schema.items === undefined) return 'array';
     const item = typeHint(schema.items);
@@ -340,3 +399,9 @@ function typeHint(schema: JsonSchema): string {
   }
   return schema.type ?? 'any';
 }
+
+/** A union cut at an alternative, never inside one. */
+function literals(alternatives: readonly string[]): string {
+  if (alternatives.length <= HINT_LITERALS) return alternatives.join('|');
+  return [...alternatives.slice(0, HINT_LITERALS), '…'].join('|');
+}

package/src/mount-errors.ts

@@ -23,7 +23,7 @@ export class McpPathDuplicateError extends UltimateError {
     super({
       code: 'X_MCP_PATH_DUPLICATE',
       cause: `${input.file} exports mcp endpoints #${first} and #${second}, and both claim ${input.method} ${input.path}`,
-      fix: `give endpoint #${second} in ${input.file} its own path — defineAppMcp({ path: '/mcp/<population>', ... }); endpoint #0 mounts at ai.mcp.path and every other at its own defineAppMcp path`,
+      fix: `give endpoint #${second} in ${input.file} its own path — defineAppMcp({ path: '/mcp/<population>', ... }); every endpoint mounts at its own defineAppMcp path (default /mcp)`,
     });
     this.path = input.path;
     this.endpoints = input.endpoints;

package/src/oauth-metadata.ts

@@ -4,7 +4,7 @@
 // authorization server(s) a client goes to for a token. The authorization server itself is the
 // APP's — its consent page, its token endpoint, its revocation list — never this package's.
 
-import { McpOAuthInvalidError } from './errors';
+import { McpOAuthInvalidError } from './errors-transport';
 
 /** The well-known suffix RFC 9728 §3 defines. */
 export const PROTECTED_RESOURCE_WELL_KNOWN = '/.well-known/oauth-protected-resource';

package/src/projectable.ts

@@ -4,28 +4,20 @@
 // primitive out is a different way to NAME a tool, never a second way to run one.
 
 import type { AnyAction } from '@ultimat3/action';
+import { actionName, guardActionBeforeInput, invoke, isAction } from '@ultimat3/action';
 import {
-  guardBeforeInput as actionGuardBeforeInput,
-  actionName,
+  type Actor,
   actorOf,
-  invoke,
-  isAction,
-} from '@ultimat3/action';
-import { type Actor, isMcpExposed, useContext } from '@ultimat3/core';
+  isMcpExposed,
+  type McpExposureDeclaration,
+  useContext,
+} from '@ultimat3/core';
 import type { AnyQuery } from '@ultimat3/query';
-import {
-  isQuery,
-  guardBeforeInput as queryGuardBeforeInput,
-  queryName,
-  readAnswer,
-  sourceFor,
-} from '@ultimat3/query';
+import { guardQueryBeforeInput, isQuery, queryName, readAnswer, sourceFor } from '@ultimat3/query';
 import { toWireOutputSchema, toWireSchema } from '@ultimat3/schema';
 import { asCallerContext } from './caller-context';
-import type { McpExposure, ProjectablePrimitive } from './from-action';
+import type { ProjectablePrimitive } from './from-action';
 import { takeIdempotencyKeyArg, withIdempotencyKeyArg } from './idempotency-arg';
-import type { McpListParams } from './list-params';
-import type { McpToolAnnotations } from './registry';
 import type { JsonSchema } from './wire';
 
 /**
@@ -33,7 +25,7 @@ import type { JsonSchema } from './wire';
  *
  * The real primitives come first because they are what an app writes: `actions: [publishPost]`.
  * Until 2026-08 this list took `ProjectablePrimitive` alone, which no `action()` or `query()`
- * structurally satisfies — they carry `as`/`tool`, never `run` — so the only value that could
+ * structurally satisfies — they carry `as` and their projections, never `run` — so the only value that could
  * reach `X_MCP_TOOL_UNDECLARED` was a hand-built fake, and the gate refused nothing an app could
  * actually declare. `ProjectablePrimitive` stays in the union for surfaces that build their
  * catalog programmatically (`@ultimat3/admin`) and for tests that project a stand-in.
@@ -75,7 +67,7 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
     admit: (actor: Actor) =>
       asCallerContext(actor, () => {
         const ctx = useContext();
-        actionGuardBeforeInput(target.policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
+        guardActionBeforeInput(target.policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
       }),
     // The actor rides in on the options: `invoke` swaps it inside the one execution path.
     run: keyed
@@ -90,7 +82,7 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
 export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
   const exposure = exposureOf(target.mcp);
   // A `single: true` read answers ONE row, or not-found — what its route answers (404) and what
-  // `tool().read()` answers. Handing an agent `[]` for a missing id said "found, and empty".
+  // `@ultimat3/query`'s `readAnswer` makes every read answer. Handing an agent `[]` for a missing id said "found, and empty".
   const single = target.single === true;
   // Only a query that DECLARED its rows (`rows: Post.$schema`) has a known answer shape. A list
   // read answers the rows as a list, so the structured copy is `{ rows }` — `structuredContent`
@@ -110,7 +102,7 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
     admit: (actor: Actor) =>
       asCallerContext(actor, () => {
         const ctx = useContext();
-        queryGuardBeforeInput(target.policy, { actor: actorOf(ctx), ctx, query: name }, 'server');
+        guardQueryBeforeInput(target.policy, { actor: actorOf(ctx), ctx, query: name }, 'server');
       }),
     run: ({ input, actor }) =>
       asCallerContext(actor, async () => {
@@ -118,7 +110,8 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
         // and is what `live`, `paginate` and `explain` build on too. Executed without the
         // cache tiers on purpose: an agent diffing two tool calls must be reading the rows,
         // not a TTL.
-        const source = await sourceFor(target, input);
+        // `'mcp'`: an agent's call spends the read's declared `rateLimit:`, the one bucket its route draws on.
+        const source = await sourceFor(target, input, { surface: 'mcp' });
         // `@ultimat3/query`'s one rule for what a read answers: rows, or a single read's row.
         return readAnswer(target, await source.execute());
       }),
@@ -138,7 +131,7 @@ export function toRowsOutputSchema(rows: unknown): JsonSchema | undefined {
 }
 
 /**
- * An action and a query declare MCP exposure with the same fields, so one typed path reads
+ * An action and a query declare core's ONE `McpExposureDeclaration`, so one typed path reads
  * both. Narrow on purpose, through `@ultimat3/core`'s `isMcpExposed`: only a literal
  * `expose: true` counts, so nothing is exposed by accident — an undeclared `mcp` block yields
  * no exposure at all.
@@ -149,7 +142,9 @@ export function toRowsOutputSchema(rows: unknown): JsonSchema | undefined {
  * projected tool was visible to every caller and the first outcome existed only for the
  * hand-written tools that build their own `McpTool`.
  */
-function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined {
+function exposureOf(
+  declared: McpExposureDeclaration | undefined,
+): McpExposureDeclaration | undefined {
   if (declared === undefined) return undefined;
   return {
     expose: isMcpExposed(declared),
@@ -160,14 +155,3 @@ function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined
     ...(declared.annotations === undefined ? {} : { annotations: declared.annotations }),
   };
 }
-
-/** `ActionMcp` and `QueryMcp` are the same shape; restating it binds to neither. */
-interface DeclaredMcp {
-  readonly expose: boolean;
-  readonly description?: string;
-  readonly visibleTo?: readonly string[];
-  /** `QueryMcp` only; an action has no list to compose. */
-  readonly listParams?: McpListParams;
-  readonly title?: string;
-  readonly annotations?: McpToolAnnotations;
-}

package/src/readonly-sql.ts

@@ -6,6 +6,7 @@
 // anywhere at statement level (which also catches a data-modifying CTE — `WITH x AS
 // (INSERT ...) SELECT`, which reads like a SELECT and is not one).
 
+import { dollarTagAt, endOfBlockComment } from '@ultimat3/db';
 import { McpNotBranchDbError, McpQueryRejectedError } from './errors';
 import { calledFunctions, forbiddenFamily } from './readonly-sql-calls';
 
@@ -216,8 +217,9 @@ function notBranch(cause: string, fix: string): McpNotBranchDbError {
 /**
  * Replace string/identifier literals and comments with spaces so keyword scanning cannot be
  * fooled by `SELECT 'delete'` (a harmless literal that looks like a write) and cannot be
- * evaded by hiding a second statement behind a block comment. Only word boundaries matter
- * downstream, so collapsing each run to one space is enough.
+ * evaded by hiding a second statement behind a block comment — ended where Postgres ends it,
+ * nesting counted (`@ultimat3/db`'s `endOfBlockComment`), or a comment closed early hides one
+ * instead. Only word boundaries matter downstream, so collapsing each run to one space is enough.
  *
  * `identifiers: 'keep'` unwraps a double-quoted identifier to its content instead — the call
  * scan needs it, because `"pg_advisory_lock"(1)` calls the function the blanked form hides.
@@ -234,11 +236,13 @@ function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = '
       continue;
     }
     if (two === '/*') {
-      const end = sql.indexOf('*/', i + 2);
-      if (end === -1) {
+      // Nested, as Postgres reads it: ending at the FIRST `*/` let `/* /* */ ' */` open a literal
+      // here that swallowed the real statement after the comment.
+      const end = endOfBlockComment(sql, i);
+      if (end === null) {
         throw unterminated('a /* block comment', 'close it with */, or use -- to the end of line');
       }
-      i = end + 2;
+      i = end;
       out += ' ';
       continue;
     }
@@ -260,26 +264,21 @@ function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = '
       i = end;
       continue;
     }
-    // Glued to an identifier, `$` is part of the NAME (`a$b$` is one identifier to Postgres), so
-    // it opens nothing — `@ultimat3/db`'s `dollarTagAt` makes the same check.
-    if (char === '$' && !IDENTIFIER_CHAR.test(sql[i - 1] ?? '')) {
-      // Postgres's own tag grammar: an identifier that does not start with a digit — letters,
-      // `_`, digits after the first, and any non-ASCII character. `[a-z_]*` read `$a1$` as text,
-      // and the `'` it then saw hid a `pg_sleep` Postgres runs outside every quote.
-      const tag = DOLLAR_TAG.exec(sql.slice(i));
-      if (tag !== null) {
-        const marker = tag[0];
-        const end = sql.indexOf(marker, i + marker.length);
-        if (end === -1) {
-          throw unterminated(
-            `a ${marker} dollar-quoted body`,
-            `close it with the same tag: ${marker} … ${marker}`,
-          );
-        }
-        i = end + marker.length;
-        out += ' ';
-        continue;
+    // `@ultimat3/db`'s lexer rule, the one copy: Postgres's tag grammar (non-ASCII included, never
+    // a leading digit — `[a-z_]*` read `$a1$` as text and hid a `pg_sleep` behind the `'` after
+    // it), and a `$` that continues an identifier (`é$x$` is one name) opens nothing.
+    const marker = char === '$' ? dollarTagAt(sql, i) : null;
+    if (marker !== null) {
+      const end = sql.indexOf(marker, i + marker.length);
+      if (end === -1) {
+        throw unterminated(
+          `a ${marker} dollar-quoted body`,
+          `close it with the same tag: ${marker} … ${marker}`,
+        );
       }
+      i = end + marker.length;
+      out += ' ';
+      continue;
     }
     out += char;
     i += 1;
@@ -289,7 +288,6 @@ function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = '
 
 const IDENTIFIER_CHAR = /[A-Za-z0-9_$\u0080-\uffff]/;
 const WORD = /[a-z_\u0080-\uffff][a-z0-9_$\u0080-\uffff]*/g;
-const DOLLAR_TAG = /^\$(?:[A-Za-z_\u0080-\uffff][A-Za-z0-9_\u0080-\uffff]*)?\$/;
 
 /**
  * `U&"` opening at a token boundary — the lexer's `xuistart`, with no space inside. `menu&"m"` is

package/src/registry.ts

@@ -131,9 +131,10 @@ export interface McpTool<A extends ToolArgs = ToolArgs> {
   /** Who may see and call this tool. Absent = everyone. See `McpVisibility`. */
   readonly visibleTo?: McpVisibility;
   /**
-   * Marks a tool that changes state. Drives the transport's rate-limit bucket and is
-   * asserted by tests over the dev server, so a new mutating tool cannot be metered as
-   * cheap read chatter by omission.
+   * Marks a tool that changes state. Drives the transport's rate-limit bucket and the meta
+   * catalog's `(action)` tag. Only `false` declares a read: an OMITTED flag counts as a write
+   * (`As of 2026-10`), as a projected action and an app tool already default — so a new mutating
+   * tool cannot be metered or listed as cheap read chatter by omission.
    */
   readonly destructive?: boolean;
   /**
@@ -309,7 +310,7 @@ export class ToolRegistry {
   verbClass(name: string): McpVerbClass {
     const tool = this.#tools.get(name);
     if (tool === undefined) return 'write';
-    return tool.destructive === true ? 'write' : 'read';
+    return tool.destructive === false ? 'read' : 'write';
   }
 }
 
@@ -326,7 +327,7 @@ export function textResult(text: string, isError = false): McpToolResult {
  * spent a third of a large answer on indentation (a staff catalog measured 32.5k characters).
  * `JSON.stringify` is deterministic for one value, so two calls still diff.
  *
- * TOTAL, because the value is an app's: `toolFromAction` hands an action's own return value
+ * TOTAL, because the value is an app's: `toolFrom` hands an action's own return value
  * straight here, and `JSON.stringify` answers `undefined` for a handler that returned nothing —
  * a `text` that is not a string is an invalid MCP frame — and THROWS on a bigint, a cycle or a
  * `toJSON` the value carries. A throw would leave the server's catch reporting a bug in the tool

package/src/scopes.ts

@@ -4,13 +4,13 @@
 // other is its authz rule, and both belong beside the code they guard. A SCOPE is neither.
 // It is a capability of the CONNECTION — what the token was issued to do — so it is grouped
 // here, once per scope, naming the tools that capability covers. That is also why
-// `toolFromAction` never invents one: a projection cannot know what a token means.
+// `toolFrom` never invents one: a projection cannot know what a token means.
 //
 // Without this map the second outcome is unreachable for a generated app. `ToolRegistry`
 // enforces `scope`, the framework's own dev tools declare one, and until 2026-08 nothing an
 // app could write ever set the field — an enforced gate no app declaration could engage.
 
-import { McpScopeConflictError, McpScopeUnknownError } from './errors';
+import { McpScopeConflictError, McpScopeUncoveredError, McpScopeUnknownError } from './errors';
 import type { AnyMcpTool } from './registry';
 
 /**
@@ -25,14 +25,19 @@ export type McpScopes = Readonly<Record<string, readonly string[]>>;
 /**
  * Attach each declared scope to the tool it covers, refusing anything ambiguous at BOOT.
  *
- * Two refusals, because both silently ship an ungated tool otherwise:
+ * Three refusals, because each silently ships an ungated tool otherwise:
  *
  *  - a name no tool in the catalog answers to (`X_MCP_SCOPE_UNKNOWN`) — a typo, or a primitive
  *    that was renamed or never listed. Skipping it leaves the tool reachable with no scope at
  *    all, which is the opposite of what the author wrote;
  *  - one tool claimed by two scopes (`X_MCP_SCOPE_CONFLICT`) — a tool carries ONE scope, so
  *    the second claim would either overwrite the first or be dropped, and which one wins would
- *    be decided by object key order.
+ *    be decided by object key order;
+ *  - a projected tool no scope names (`X_MCP_SCOPE_UNCOVERED`). The registry gates a tool only
+ *    when it carries a scope, so an unnamed one answered EVERY token — while `bearerMount`, handed
+ *    the same map, serves an unnamed primitive to nobody. Giving a map is declaring the cut; a
+ *    tool outside it is a mistake, not a public tool. A tool that arrived with its own `scope`
+ *    (a ready `McpTool`) is covered by it.
  *
  * Runs AFTER duplicate names are refused, so a name resolves to exactly one tool.
  */
@@ -64,6 +69,12 @@ export function withScopes(
     }
   }
 
+  const uncovered = tools
+    .filter((tool) => tool.scope === undefined && !required.has(tool.name))
+    .map((tool) => tool.name)
+    .sort();
+  if (uncovered.length > 0) throw new McpScopeUncoveredError({ uncovered });
+
   return tools.map((tool) => {
     const scope = required.get(tool.name);
     return scope === undefined ? tool : { ...tool, scope };

package/src/server-voice.ts

@@ -8,7 +8,7 @@ import { formatIssues } from '@ultimat3/schema';
 import type { McpCaller, McpToolResult } from './registry';
 import type { ArgIssue } from './validate-args';
 
-/** See `CreateMcpServerInput.instructions`. */
+/** See `McpServerInput.instructions`. */
 export type McpInstructions = string | ((caller: McpCaller) => string | undefined);
 
 /** The server's per-caller wording: `initialize`'s advice and the audience of every `fix:` line. */