@ultimat3/mcp 22.9.0 → 22.10.0

package/CLAUDE.md

@@ -35,6 +35,7 @@ import. The CLI wires it.
 | `meta-surface.ts` | `surface: 'meta'` catalog: `list_resources` / `describe_resource`, `groups:` boot checks; dispatch stays in `server.ts` |
 | `list-params.ts` | `listParams` whitelist → the schema `manage_resource` enforces (flat keys: `status_eq`) |
 | `meta-errors.ts` · `framework-error.ts` | meta boot refusals · a thrown value read and rendered (split from `server.ts`) |
+| `server-voice.ts` · `surface-budget.ts` | `instructions`, `errorAudience`, the invalid-args RESULT · `tools/list`/`list_resources` size, measured and budgeted |
 
 ## Invariants
 
@@ -266,6 +267,10 @@ import. The CLI wires it.
   carrying a `fix`, then the rest of that line is DISCARDED to the next newline: what follows an
   over-long message on the same line is its tail, never a message of its own.
 - New mutating tool ⇒ set `destructive: true`, or it is metered as cheap read chatter.
+- **Invalid arguments are an `isError` RESULT (`X_INPUT_INVALID`), `As of 22.10`** — clients hide a
+  `-32602` from the model. Audit outcome stays `invalid-args`. `-32602` only for a call that is not
+  one. An app server renders `callerFix` (`errorAudience: 'caller'`); a `docs` other than
+  `ERROR_DOCS_URL` is a 4th line — branded errors only, `fix`'s trust rule.
 
 ## Commands
 

package/README.md

@@ -111,6 +111,7 @@ export const mcp = defineAppMcp({
     },
   },
   scopes: { 'admin:seats': ['seatReport'] },   // scope name → tool NAMES, by string
+  instructions: 'Admin console. seatReport({}) answers seat questions; writes are audited.',
   resolveToken: (token) => sessions.resolveAgentToken(token),
 });
 
@@ -201,7 +202,7 @@ defineAppMcp({
 
 | Tool | Answers |
 |---|---|
-| `list_resources` | `{ resources: [{ name, description, actions: [{ name, kind: 'query'\|'action', description, params, confirms?, scope? }] }] }` — `params` is a one-line hint (`batchId: string, note?: string`) |
+| `list_resources` | PLAIN TEXT (`As of 22.10`; JSON until then): one line per resource, and under it one line per action — `  previewPayoutBatch (action; confirms; scope payouts:write) {batchId: string, note?: string} — <description>`. The same catalog as data: `server.catalog(caller)` (`MetaResource[]`, `undefined` for a flat caller); the renderer is `renderCatalog` |
 | `describe_resource` | `{ resources: string[] }` (batched) → each action's full `inputSchema` |
 | `manage_resource` | `{ resource, action, params }` → the flat tool's answer, byte for byte |
 
@@ -218,9 +219,39 @@ meta tool name taken by an app tool (`X_MCP_TOOL_DUPLICATE`).
 maxLimit: 100 } }`. Keys are FLAT — `status_eq`, `createdAt_gt`, `sort: '-createdAt'`, `fields`,
 `cursor` (opaque keyset), `limit` — because a query's input travels as a query string; the query's
 own `input` declares them and implements them. `describe_resource` publishes the whitelist and
-`manage_resource` refuses anything outside it (`X_MCP_ARGS_INVALID`) before the query runs; a
+`manage_resource` refuses anything outside it (an `isError` result carrying `X_INPUT_INVALID`) before the query runs; a
 whitelisted key the input does not declare is `X_MCP_LIST_PARAMS_INVALID` at boot.
 
+### What a client is told beyond the schema
+
+`As of 22.10`, MCP 2025-06-18. The projection derives each from the declaration; the primitive's
+`mcp` block overrides.
+
+| Field | Source | Default |
+|---|---|---|
+| `initialize.instructions` | `defineAppMcp({ instructions })` / `createMcpServer({ instructions })` — a string, or `(caller) => string \| undefined` | none; a function that throws or answers blank sends none |
+| `title` | `mcp: { title }` · hand-written `title` | none |
+| `annotations` | `deriveAnnotations(primitive)`, then `mcp: { annotations }` key by key | query `{ readOnlyHint: true }`; action `{ readOnlyHint: false, destructiveHint: true, idempotentHint: <idempotent> }`; `openWorldHint` only when declared |
+| `outputSchema` | an action's `output` with an object root; a query's `rows` as `{ rows: [<row>] }` — `toOutputSchema` / `toRowsOutputSchema`, structure only (no bounds, patterns or `additionalProperties`: a client refuses a result that misses its schema) | none |
+| `structuredContent` | `structuredResult(value, wrap?)`: the serialized answer read back, beside the text block | absent |
+
+A tool's text is **compact JSON** (`jsonResult`; the 2-space form until 22.10). The meta tools
+carry their own hints: `list_resources` and `describe_resource` read-only, `manage_resource` a
+write.
+
+**Budget test.** `measureMcpSurface(server, caller)` answers `{ toolsList, listResources,
+instructions }` in characters, as serialized on the wire; `assertMcpSurfaceBudget(server, caller,
+{ toolsList, listResources, instructions })` throws `X_MCP_SURFACE_OVER_BUDGET` naming every
+surface over its ceiling. Put the derivation beside the number.
+
+**Whose fix.** `errorAudience: 'caller'` (`defineAppMcp`'s default) renders an error's
+`callerFix` — `X_FORBIDDEN`: ask the account owner for the permission; `X_MCP_SCOPE_DENIED`: ask for
+a token with the scope; `X_INPUT_INVALID`: correct the named fields — where `fix` names something
+only the app's developer can run. `'developer'` (`createMcpServer`'s default, the dev server's)
+keeps `fix`. An error whose `docs` is not the framework's one Error-Codes page — an app's
+`docs://recipes/...` — renders a fourth `docs:` line. Byte-identical to
+`UltimateError.format({ audience, docs })`.
+
 ## Transports
 
 | Transport | Entry | Auth |
@@ -287,6 +318,12 @@ implements the emitted subset (objects, arrays, enums, `required`, `additionalPr
 bounds, `default`) and applies declared defaults. Actions still re-parse authoritatively
 inside their own handler.
 
+A call that fails it is a **tool result** with `isError: true` — `X_INPUT_INVALID`, the code HTTP
+answers for the same input, each issue addressed by path (`input for tool "publishPost" failed
+validation: postId: required`) — `As of 22.10`. It was a JSON-RPC `-32602` until then, and clients
+surface a protocol error to the human and hide it from the model, which then retried blind.
+`-32602` remains for a call that is not one: no `params`, a non-string `name`.
+
 ## Idempotency over MCP
 
 An `idempotent: true` action's tool carries one reserved, optional argument,
@@ -301,7 +338,7 @@ key — so an agent retrying a timed-out call with the same key gets the first r
 ```
 
 The action's own input never sees the key. A non-idempotent tool does not advertise it and refuses
-it (`X_MCP_ARGS_INVALID`). An argument, not `params._meta`: `_meta` is for host metadata and a
+it (`X_INPUT_INVALID`, as an `isError` result). An argument, not `params._meta`: `_meta` is for host metadata and a
 model-driven client cannot set it. An idempotent action whose input already names `idempotencyKey`
 is `X_MCP_IDEMPOTENCY_KEY_SHADOWED` at boot.
 
@@ -313,7 +350,9 @@ is `X_MCP_IDEMPOTENCY_KEY_SHADOWED` at boot.
 | `X_MCP_SCOPE_DENIED` | visible, but the connection's token lacks the scope |
 | `X_MCP_SCOPE_UNKNOWN` | `defineAppMcp`'s `scopes:` names a tool this server does not project |
 | `X_MCP_SCOPE_CONFLICT` | two scopes in `defineAppMcp`'s `scopes:` claim one tool |
-| `X_MCP_ARGS_INVALID` | arguments failed the declared schema |
+| `X_INPUT_INVALID` | arguments failed the published `inputSchema` — an `isError` result since 22.10 |
+| `X_MCP_ARGS_INVALID` | no longer raised on the wire (22.10); `McpArgsInvalidError` stays exported |
+| `X_MCP_SURFACE_OVER_BUDGET` | `assertMcpSurfaceBudget` measured a surface over its declared ceiling |
 | `X_MCP_IDEMPOTENCY_KEY_SHADOWED` | an idempotent action's input declares `idempotencyKey`, the reserved retry-key argument |
 | `X_MCP_PROTOCOL` | malformed envelope, unknown method, bad auth header |
 | `X_MCP_QUERY_REJECTED` | `db.query` given anything but one read-only statement |
@@ -347,6 +386,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `McpScopeConflictError` | `X_MCP_SCOPE_CONFLICT` | `src/errors.ts` |
 | `McpScopeDeniedError` | `X_MCP_SCOPE_DENIED` | `src/errors.ts` |
 | `McpScopeUnknownError` | `X_MCP_SCOPE_UNKNOWN` | `src/errors.ts` |
+| `McpSurfaceOverBudgetError` | `X_MCP_SURFACE_OVER_BUDGET` | `src/errors.ts` |
 | `McpToolDuplicateError` | `X_MCP_TOOL_DUPLICATE` | `src/errors.ts` |
 | `McpToolUndeclaredError` | `X_MCP_TOOL_UNDECLARED` | `src/errors.ts` |
 | `McpToolUnknownError` | `X_MCP_TOOL_UNKNOWN` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "22.9.0",
+  "version": "22.10.0",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.9.0",
-    "@ultimat3/core": "22.9.0",
-    "@ultimat3/entity": "22.9.0",
-    "@ultimat3/http": "22.9.0",
-    "@ultimat3/jobs": "22.9.0",
-    "@ultimat3/policy": "22.9.0",
-    "@ultimat3/query": "22.9.0",
-    "@ultimat3/schema": "22.9.0"
+    "@ultimat3/action": "22.10.0",
+    "@ultimat3/core": "22.10.0",
+    "@ultimat3/entity": "22.10.0",
+    "@ultimat3/http": "22.10.0",
+    "@ultimat3/jobs": "22.10.0",
+    "@ultimat3/policy": "22.10.0",
+    "@ultimat3/query": "22.10.0",
+    "@ultimat3/schema": "22.10.0"
   }
 }

package/src/app-tool.ts

@@ -21,7 +21,7 @@ import { asCallerContext } from './caller-context';
 import { McpToolUnsafeError } from './errors';
 import type { ProjectablePrimitive } from './from-action';
 import { toWireSchema } from './input-schema';
-import type { McpRole } from './registry';
+import type { McpRole, McpToolAnnotations } from './registry';
 
 export interface AppToolArgs<TInput extends StandardSchemaV1> {
   readonly input: InferOutput<TInput>;
@@ -43,6 +43,13 @@ export interface AppToolDefinition<TInput extends StandardSchemaV1 = StandardSch
    * rate-limit bucket, so forgetting the flag costs throughput rather than safety.
    */
   readonly destructive?: boolean;
+  /** Display name for a client's UI. Absent: none published. */
+  readonly title?: string;
+  /**
+   * Overrides of the derived hints — `readOnlyHint: !destructive`, and for a write
+   * `destructiveHint: true`, `idempotentHint: false`. See `McpToolAnnotations`.
+   */
+  readonly annotations?: McpToolAnnotations;
   // Method syntax (not a property) so a tool declared with narrower args stays assignable.
   handle(args: AppToolArgs<TInput>): unknown;
 }
@@ -54,6 +61,8 @@ export interface AnyAppToolDefinition {
   readonly policy: KnownPermission;
   readonly visibleTo?: readonly McpRole[];
   readonly destructive?: boolean;
+  readonly title?: string;
+  readonly annotations?: McpToolAnnotations;
   handle(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
 }
 
@@ -89,6 +98,8 @@ export function appToolPrimitive(name: string, def: AnyAppToolDefinition): Proje
       expose: true,
       description: def.description,
       ...(visibleTo !== undefined ? { visibleTo } : {}),
+      ...(def.title !== undefined ? { title: def.title } : {}),
+      ...(def.annotations !== undefined ? { annotations: def.annotations } : {}),
     },
     inputJsonSchema: toWireSchema(def.input),
     mutates: def.destructive ?? true,

package/src/app-tools.ts

@@ -8,6 +8,7 @@
 // Deliberately one function: an app author should never have to know that `ToolRegistry`,
 // `frameworkResources` and `mcpHttpRoute` exist.
 
+import type { ErrorAudience } from '@ultimat3/core';
 import type { RateLimitStore } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { AnyAppToolDefinition, AppTools } from './app-tool';
@@ -26,6 +27,7 @@ import type { McpScopes } from './scopes';
 import { withScopes } from './scopes';
 import type { CreateMcpServerInput } from './server';
 import { createMcpServer, type McpServer } from './server';
+import type { McpInstructions } from './server-voice';
 import type { McpRouteDescriptor, ResolvedToken } from './transport-http';
 import { mcpHttpRoute } from './transport-http';
 
@@ -96,6 +98,29 @@ export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSche
    * answers to is `X_MCP_GROUP_UNKNOWN`, a tool in two groups `X_MCP_GROUP_CONFLICT`.
    */
   readonly groups?: McpResourceGroups;
+  /**
+   * `initialize`'s `instructions` — the advice a client that honours it puts in the model's context:
+   * the entry-point call, the three or four goals most sessions are, the traps. A string, or a
+   * function of the caller for per-population advice (the same shape as `surface`):
+   *
+   * ```ts
+   * instructions: (caller) =>
+   *   caller.role?.startsWith('staff')
+   *     ? 'Staff console. Start with list_resources({}); writes are audited.'
+   *     : 'Start with docs({}) — recipes for sending a notification and reading its evidence.',
+   * ```
+   *
+   * An upgrade, never a dependency: many clients drop it, so the same advice belongs in the tool
+   * descriptions too.
+   */
+  readonly instructions?: McpInstructions;
+  /**
+   * Whose `fix:` line a refusal carries. Defaults to `'caller'`: this server answers remote agents,
+   * so an error that declares a `callerFix` (a denial, a missing scope, an invalid argument) renders
+   * it — "ask the account owner to grant post:publish" — instead of the developer's
+   * `x policy explain …`, which stays in the log line. `'developer'` restores the author's fix.
+   */
+  readonly errorAudience?: ErrorAudience;
   /** Bearer-token resolution. Omit to expose no HTTP route (stdio/embedded only). */
   resolveToken?(token: string): Promise<ResolvedToken | null> | ResolvedToken | null;
   /** Mount path. Defaults to `/mcp`. */
@@ -199,6 +224,8 @@ export function defineAppMcp<TSchemas extends AppToolSchemas>(
     serverInfo: { name: input.name ?? 'ultimate-app', version: input.version ?? '0.0.0' },
     ...(input.surface === undefined ? {} : { surface: input.surface }),
     ...(input.groups === undefined ? {} : { groups: input.groups }),
+    ...(input.instructions === undefined ? {} : { instructions: input.instructions }),
+    errorAudience: input.errorAudience ?? 'caller',
   };
   const server = createMcpServer(config);
 

package/src/errors.ts

@@ -25,6 +25,7 @@ export const MCP_ERROR_CODES = [
   'X_MCP_LIST_PARAMS_INVALID',
   'X_MCP_OAUTH_INVALID',
   'X_MCP_IDEMPOTENCY_KEY_SHADOWED',
+  'X_MCP_SURFACE_OVER_BUDGET',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -52,6 +53,7 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_OAUTH_INVALID: 'the MCP oauth block cannot be published as protected-resource metadata',
   X_MCP_IDEMPOTENCY_KEY_SHADOWED:
     "an idempotent action's input declares idempotencyKey, the MCP argument reserved for the idempotency key",
+  X_MCP_SURFACE_OVER_BUDGET: "an MCP surface an agent reads is larger than the app's budget for it",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -119,6 +121,8 @@ export class McpScopeDeniedError extends UltimateError {
         subject === 'tool'
           ? `reconnect with a token whose scopes include "${input.scope}" — the app's resolveToken(token) is what returns them — or drop "${input.scope}" from defineAppMcp({ scopes }); scopes are fixed for the life of a connection`
           : `reconnect with a token whose scopes include "${input.scope}" — the app's resolveToken(token) is what returns them — or drop scope: '${input.scope}' from the resource declaring "${input.name}"; scopes are fixed for the life of a connection`,
+      // The agent's half: it cannot edit `defineAppMcp`, and its token is what it can change.
+      callerFix: `this token was not granted scope "${input.scope}": ask the account owner for a token that includes it, then reconnect — scopes are fixed for the life of a connection, so retrying on this one is refused the same way`,
     });
     this.scope = input.scope;
   }
@@ -449,3 +453,24 @@ export class McpIdempotencyKeyShadowedError extends UltimateError {
     });
   }
 }
+
+/**
+ * `assertMcpSurfaceBudget` measured a surface over the character budget the app declared for it.
+ * Every over-budget surface is named in one throw, so one edit closes all of them.
+ */
+export class McpSurfaceOverBudgetError extends UltimateError {
+  constructor(input: {
+    readonly over: readonly {
+      readonly surface: string;
+      readonly size: number;
+      readonly budget: number;
+    }[];
+  }) {
+    super({
+      code: 'X_MCP_SURFACE_OVER_BUDGET',
+      cause: `over budget: ${input.over.map((o) => `${o.surface} is ${o.size} characters, budget ${o.budget}`).join('; ')}`,
+      fix: "shorten the tool descriptions or instructions it names, group tools behind surface: 'meta', or raise the budget with the measured size and the reason in the same diff",
+      meta: { over: input.over },
+    });
+  }
+}

package/src/framework-error.ts

@@ -2,7 +2,15 @@
 // and its rendering, byte-identical to `UltimateError.format()`. Split from `server.ts`, whose two
 // dispatch paths (a flat `tools/call` and `manage_resource`) and resource reads all share it.
 
-import { FRAMEWORK_CODE, singleLine, stringField } from '@ultimat3/core';
+import type { ErrorAudience } from '@ultimat3/core';
+import {
+  ERROR_DOCS_URL,
+  FRAMEWORK_CODE,
+  fixFor,
+  isUltimateError,
+  singleLine,
+  stringField,
+} from '@ultimat3/core';
 
 export interface FrameworkError {
   readonly code: string;
@@ -10,6 +18,14 @@ export interface FrameworkError {
   readonly title: string;
   readonly cause: string;
   readonly fix: string;
+  /** The remote caller's fix, when the error declared one (`UltimateErrorInit.callerFix`). */
+  readonly callerFix?: string;
+  /**
+   * Where the reader goes next, ONLY when it is not the framework's one Error-Codes page — an app's
+   * `docs://recipes/...` guide. The default page is the same URL on every error and names nothing
+   * about this one, so it is not worth a line of an agent's context.
+   */
+  readonly docs?: string;
 }
 
 /**
@@ -29,6 +45,12 @@ export function asFrameworkError(error: unknown): FrameworkError | undefined {
   // `X_SCREAMING_SNAKE` and nothing else, so a value that is not one is not a framework error —
   // it takes the `-32603` branch, which leaks nothing of the throw.
   if (code === undefined || !FRAMEWORK_CODE.test(code)) return undefined;
+  // BRANDED only, for `@ultimat3/http`'s `factsOf` reason: `callerFix` and `docs` are lines an
+  // agent is told to act on, and an `UltimateError` built them in this process. A foreign object's
+  // are remote text.
+  const branded = isUltimateError(error);
+  const callerFix = branded ? stringField(error, 'callerFix') : undefined;
+  const docs = branded ? stringField(error, 'docs') : undefined;
   return {
     code,
     title: stringField(error, 'title') ?? '',
@@ -37,22 +59,37 @@ export function asFrameworkError(error: unknown): FrameworkError | undefined {
     // named no docs and no command; `code` is already narrowed to an `X_` string by the guard
     // above, so the substitute is the one command that explains exactly this code.
     fix: stringField(error, 'fix') ?? `x errors explain ${code}`,
+    ...(callerFix === undefined ? {} : { callerFix }),
+    ...(docs === undefined || docs === '' || docs === ERROR_DOCS_URL ? {} : { docs }),
   };
 }
 
 /**
- * The agent-readable form, BYTE-IDENTICAL to `UltimateError.format()` — one denial reads the
- * same over MCP as it does in the terminal, so an agent that learned the shape from `x` does
- * not have to learn a second one here. Dropping the title would be a second rendering of the
- * same contract, and the two would drift.
+ * The agent-readable form, BYTE-IDENTICAL to `UltimateError.format({ audience })` — plus
+ * `{ docs: true }` when the error names a page of its own — so one denial reads the same over MCP
+ * as it does in the terminal, and an agent that learned the shape from `x` does not have to learn a
+ * second one here. Dropping the title would be a second rendering of the same contract, and the two
+ * would drift.
+ *
+ * `audience` is the server's (`createMcpServer({ errorAudience })`): an app's server answers remote
+ * agents, who cannot run `x policy explain`, so it renders `callerFix` where the error has one.
  *
  * The bare-`code` head is the fallback for a foreign thrown object that carries `code`/`cause`
  * but no title; a real `UltimateError` always has one.
  */
-export function renderFrameworkError(error: FrameworkError): string {
+export function renderFrameworkError(
+  error: FrameworkError,
+  audience: ErrorAudience = 'developer',
+): string {
   const head =
     error.title === ''
       ? singleLine(error.code)
       : `${singleLine(error.code)}: ${singleLine(error.title)}`;
-  return `${head}\n  cause: ${singleLine(error.cause)}\n  fix:   ${singleLine(error.fix)}`;
+  const lines = [
+    head,
+    `  cause: ${singleLine(error.cause)}`,
+    `  fix:   ${singleLine(fixFor(error, audience))}`,
+  ];
+  if (error.docs !== undefined) lines.push(`  docs:  ${singleLine(error.docs)}`);
+  return lines.join('\n');
 }

package/src/from-action.ts

@@ -28,8 +28,15 @@ import type { Actor } from '@ultimat3/core';
 import { isMcpExposed } from '@ultimat3/core';
 import { McpToolUndeclaredError } from './errors';
 import type { McpListParams } from './list-params';
-import type { AnyMcpTool, McpCaller, McpRole, McpToolResult, ToolArgs } from './registry';
-import { jsonResult } from './registry';
+import type {
+  AnyMcpTool,
+  McpCaller,
+  McpRole,
+  McpToolAnnotations,
+  McpToolResult,
+  ToolArgs,
+} from './registry';
+import { jsonResult, structuredResult } from './registry';
 import type { JsonSchema } from './wire';
 import { NO_ARGS } from './wire';
 
@@ -50,6 +57,13 @@ export interface McpExposure {
   readonly visibleTo?: readonly McpRole[];
   /** Override the projected tool name. Defaults to the primitive's own name. */
   readonly name?: string;
+  /** Display name for a client's UI. Contract text, like `description`. Absent: none published. */
+  readonly title?: string;
+  /**
+   * Overrides of the derived hints, key by key — see `deriveAnnotations`. The one declaration an
+   * app writes for a write that destroys nothing: `annotations: { destructiveHint: false }`.
+   */
+  readonly annotations?: McpToolAnnotations;
   /** A list query's whitelist, carried to the tool for the meta surface. See `McpListParams`. */
   readonly listParams?: McpListParams;
 }
@@ -68,6 +82,18 @@ export interface ProjectablePrimitive {
   readonly inputJsonSchema?: JsonSchema;
   /** True for a mutation. Drives the rate-limit bucket; queries set it false. */
   readonly mutates?: boolean;
+  /** The action honours an idempotency key — a repeat is answered, not re-run. */
+  readonly idempotent?: boolean;
+  /**
+   * The `outputSchema` to publish, already narrowed (`toOutputSchema`) and with an OBJECT root.
+   * Absent: no `outputSchema`, no `structuredContent` — only the text block.
+   */
+  readonly outputJsonSchema?: JsonSchema;
+  /**
+   * The key an ARRAY answer is published under in `structuredContent` — `rows` for a query, whose
+   * answer is a list and whose `outputSchema` is `{ rows: [<row>] }`. Absent: the answer IS the object.
+   */
+  readonly outputWrap?: string;
   /** The one server-authoritative entry point. Runs policy, then the handler. */
   run(args: { input: unknown; actor: Actor }): Promise<unknown>;
 }
@@ -92,11 +118,17 @@ export function toolFromAction(primitive: ProjectablePrimitive): AnyMcpTool {
   const mutates = primitive.mutates ?? true;
   const visibleTo = primitive.mcp?.visibleTo;
   const listParams = primitive.mcp?.listParams;
+  const title = primitive.mcp?.title;
+  const outputSchema = primitive.outputJsonSchema;
+  const wrap = primitive.outputWrap;
 
   return {
     name,
+    ...(title !== undefined ? { title } : {}),
     description,
     inputSchema: primitive.inputJsonSchema ?? NO_ARGS,
+    ...(outputSchema !== undefined ? { outputSchema } : {}),
+    annotations: deriveAnnotations(primitive),
     destructive: mutates,
     ...(visibleTo !== undefined ? { visibleTo } : {}),
     ...(listParams !== undefined ? { listParams } : {}),
@@ -106,11 +138,51 @@ export function toolFromAction(primitive: ProjectablePrimitive): AnyMcpTool {
       // same `invoke` with an actor of kind 'user', MCP arrives with kind 'agent'. Same
       // policy, same decision.
       const output = await primitive.run({ input: args, actor: caller.actor });
-      return jsonResult(output);
+      return outputSchema === undefined ? jsonResult(output) : structuredResult(output, wrap);
     },
   };
 }
 
+/**
+ * The MCP hints a primitive's KIND already answers, with the author's `mcp.annotations` laid over
+ * them key by key:
+ *
+ * | primitive | readOnlyHint | destructiveHint | idempotentHint |
+ * |---|---|---|---|
+ * | query (`mutates: false`) | `true` | — | — |
+ * | action | `false` | `true` | `idempotent: true` on the action |
+ *
+ * `destructiveHint: true` for every action is the spec's own default made explicit, and the only
+ * safe one: the framework cannot tell an insert from a delete. `openWorldHint` is never derived —
+ * only the author knows whether a write sends mail.
+ */
+export function deriveAnnotations(primitive: ProjectablePrimitive): McpToolAnnotations {
+  const derived: McpToolAnnotations =
+    (primitive.mutates ?? true)
+      ? {
+          readOnlyHint: false,
+          destructiveHint: true,
+          idempotentHint: primitive.idempotent === true,
+        }
+      : { readOnlyHint: true };
+  return { ...derived, ...definedOnly(primitive.mcp?.annotations) };
+}
+
+/**
+ * The four hint keys, and only booleans: an override's explicit `undefined` must not erase a
+ * derived hint, and a key the spec does not define is not published on its behalf.
+ */
+function definedOnly(annotations: McpToolAnnotations | undefined): McpToolAnnotations {
+  if (annotations === undefined) return {};
+  const { readOnlyHint, destructiveHint, idempotentHint, openWorldHint } = annotations;
+  return {
+    ...(typeof readOnlyHint === 'boolean' ? { readOnlyHint } : {}),
+    ...(typeof destructiveHint === 'boolean' ? { destructiveHint } : {}),
+    ...(typeof idempotentHint === 'boolean' ? { idempotentHint } : {}),
+    ...(typeof openWorldHint === 'boolean' ? { openWorldHint } : {}),
+  };
+}
+
 /** Alias that reads correctly at a query call site — same projection, same guarantees. */
 export const toolFromQuery = toolFromAction;
 

package/src/index.ts

@@ -73,6 +73,7 @@ export {
   McpScopeConflictError,
   McpScopeDeniedError,
   McpScopeUnknownError,
+  McpSurfaceOverBudgetError,
   McpToolDuplicateError,
   McpToolUndeclaredError,
   McpToolUnknownError,
@@ -81,6 +82,7 @@ export {
 export { exposedPrimitives } from './exposed';
 export type { McpExposure, ProjectablePrimitive } from './from-action';
 export {
+  deriveAnnotations,
   isExposed,
   toolFromAction,
   toolFromQuery,
@@ -88,7 +90,7 @@ export {
   toolsListed,
 } from './from-action';
 export { MCP_IDEMPOTENCY_KEY_ARG } from './idempotency-arg';
-export { toWireSchema } from './input-schema';
+export { toOutputSchema, toRowsOutputSchema, toWireSchema } from './input-schema';
 export type { ListFilterOp, McpListParams } from './list-params';
 export { DEFAULT_LIST_MAX_LIMIT, listParamsSchema } from './list-params';
 export {
@@ -113,6 +115,7 @@ export {
   MANAGE_RESOURCE,
   META_TOOL_NAMES,
   oneLineParams,
+  renderCatalog,
 } from './meta-surface';
 export type { McpOAuth } from './oauth-metadata';
 export {
@@ -136,6 +139,7 @@ export type {
   McpCaller,
   McpRole,
   McpTool,
+  McpToolAnnotations,
   McpToolResult,
   McpVerbClass,
   McpVisibility,
@@ -143,7 +147,14 @@ export type {
   ToolListEntry,
   ToolResolution,
 } from './registry';
-export { jsonResult, ToolRegistry, textResult, visibleToCaller } from './registry';
+export {
+  jsonResult,
+  structuredResult,
+  ToolRegistry,
+  textResult,
+  toolListEntry,
+  visibleToCaller,
+} from './registry';
 export type {
   FrameworkResourceProviders,
   McpPrompt,
@@ -164,6 +175,9 @@ export type { McpScopes } from './scopes';
 export { withScopes } from './scopes';
 export type { CreateMcpServerInput, McpWire } from './server';
 export { createMcpServer, McpServer } from './server';
+export type { McpInstructions, McpServerVoice } from './server-voice';
+export type { McpSurfaceBudget, McpSurfaceSize } from './surface-budget';
+export { assertMcpSurfaceBudget, measureMcpSurface } from './surface-budget';
 export type {
   McpHttpTransportInput,
   McpProtectedResource,

package/src/input-schema.ts

@@ -75,3 +75,66 @@ function narrowAdditional(value: boolean | RichJsonSchema | undefined): {
   if (value === undefined) return {};
   return { additionalProperties: typeof value === 'boolean' ? value : true };
 }
+
+/**
+ * A Standard Schema → the `outputSchema` a tool publishes, or `undefined` when its root is not an
+ * object (MCP's `structuredContent` is one) or it cannot be introspected.
+ *
+ * STRUCTURE ONLY — type, properties, required, items, enum, const, anyOf, title, description. A
+ * client validates `structuredContent` against this document and refuses the call on a miss, so
+ * every keyword here is a promise about a value the server produced: a bound, a pattern or
+ * `additionalProperties: false` on a query's rows (read from the database, never re-parsed) is a
+ * promise nothing enforces on the way out. Fewer constraints is the honest projection of an output.
+ */
+export function toOutputSchema(schema: unknown): JsonSchema | undefined {
+  let rich: RichJsonSchema;
+  try {
+    rich = toMcpInputSchema(schema);
+  } catch {
+    return undefined;
+  }
+  if (rich.type !== 'object') return undefined;
+  return shape(rich);
+}
+
+/** `{ rows: [<row>] }` — a query's answer as `structuredContent`. `undefined` when no row schema. */
+export function toRowsOutputSchema(rows: unknown): JsonSchema | undefined {
+  if (rows === undefined) return undefined;
+  const row = toOutputSchema(rows);
+  if (row === undefined) return undefined;
+  return {
+    type: 'object',
+    properties: { rows: { type: 'array', items: row } },
+    required: ['rows'],
+  };
+}
+
+function shape(source: RichJsonSchema): JsonSchema {
+  return {
+    ...(source.type === undefined ? {} : { type: source.type }),
+    ...(source.title === undefined ? {} : { title: source.title }),
+    ...(source.description === undefined ? {} : { description: source.description }),
+    ...(source.properties === undefined ? {} : { properties: shapeProperties(source.properties) }),
+    ...(source.required === undefined ? {} : { required: source.required }),
+    ...(source.items === undefined ? {} : { items: shape(source.items) }),
+    ...(source.enum === undefined ? {} : { enum: source.enum }),
+    ...(source.const === undefined ? {} : { const: source.const }),
+    ...(source.anyOf === undefined ? {} : { anyOf: source.anyOf.map(shape) }),
+  };
+}
+
+function shapeProperties(
+  properties: Readonly<Record<string, RichJsonSchema>>,
+): Readonly<Record<string, JsonSchema>> {
+  const out: Record<string, JsonSchema> = {};
+  for (const [key, child] of Object.entries(properties)) {
+    // `narrowProperties`' reason: `out['__proto__'] = …` re-prototypes instead of adding a key.
+    Object.defineProperty(out, key, {
+      value: shape(child),
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
+  }
+  return out;
+}

package/src/meta-call.ts

@@ -5,9 +5,15 @@
 import { auditToolCall } from './audit';
 import { META_UNKNOWN_FIX } from './meta-errors';
 import type { MetaSurface } from './meta-surface';
-import { DESCRIBE_RESOURCE, LIST_RESOURCES, META_TOOL_ENTRIES, schemaOf } from './meta-surface';
+import {
+  DESCRIBE_RESOURCE,
+  LIST_RESOURCES,
+  META_TOOL_ENTRIES,
+  renderCatalog,
+  schemaOf,
+} from './meta-surface';
 import type { McpCaller, ToolRegistry, ToolResolution } from './registry';
-import { jsonResult } from './registry';
+import { jsonResult, textResult } from './registry';
 import { validateArgs } from './validate-args';
 import type { JsonRpcId, JsonRpcResponse } from './wire';
 import { errorResponse, METHOD_NOT_FOUND, resultResponse } from './wire';
@@ -48,7 +54,7 @@ export async function metaCall(
   }
   if (name === LIST_RESOURCES) {
     auditToolCall({ tool: name, outcome: 'ok', caller });
-    return resultResponse(id, jsonResult({ resources: meta.listResources(caller) }));
+    return resultResponse(id, textResult(renderCatalog(meta.listResources(caller))));
   }
   if (name === DESCRIBE_RESOURCE) {
     const described = meta.describe(args.value['resources'] as readonly string[], caller);