@ultimat3/mcp 22.9.1 → 22.11.0

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);
@@ -77,7 +83,9 @@ export async function metaCall(
   let resolved = host.tools.resolve(action, input, caller);
   if (resolved.kind !== 'scope-denied' && resolved.kind !== 'not-found') {
     const listed = validateArgs(schemaOf(tool), input);
-    if (!listed.ok) resolved = { kind: 'invalid-args', name: action, issues: listed.issues };
+    if (!listed.ok) {
+      resolved = { kind: 'invalid-args', name: action, issues: listed.issues, tool };
+    }
   }
   return host.dispatch(id, action, resolved, caller);
 }

package/src/meta-surface.ts

@@ -50,6 +50,7 @@ export const META_TOOL_NAMES: readonly string[] = [
 export const META_TOOL_ENTRIES: readonly ToolListEntry[] = [
   {
     name: DESCRIBE_RESOURCE,
+    title: 'Describe resources',
     description:
       "Full input schemas for the actions of one or more resources (batched). Call it before manage_resource when list_resources' one-line params are not enough. Read-only.",
     inputSchema: {
@@ -58,15 +59,19 @@ export const META_TOOL_ENTRIES: readonly ToolListEntry[] = [
       required: ['resources'],
       additionalProperties: false,
     },
+    annotations: { readOnlyHint: true, openWorldHint: false },
   },
   {
     name: LIST_RESOURCES,
+    title: 'List resources',
     description:
       'The catalog: every resource this caller may use, each with its actions (query or action), a one-line parameter hint and whether a write waits for a human to confirm. Read-only.',
     inputSchema: NO_ARGS,
+    annotations: { readOnlyHint: true, openWorldHint: false },
   },
   {
     name: MANAGE_RESOURCE,
+    title: 'Manage a resource',
     description:
       'Run one action of one resource: { resource, action, params }. Same policies, scopes and audit as calling the action directly. Writes may change state or send mail — read the action first.',
     inputSchema: {
@@ -79,6 +84,9 @@ export const META_TOOL_ENTRIES: readonly ToolListEntry[] = [
       required: ['resource', 'action'],
       additionalProperties: false,
     },
+    // The door to every grouped tool, reads and writes alike: a client has to assume the worst of
+    // it. `list_resources` says per action which is which.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
   },
 ];
 
@@ -254,6 +262,40 @@ export function schemaOf(tool: AnyMcpTool): JsonSchema {
     : listParamsSchema(tool.listParams, tool.inputSchema);
 }
 
+/**
+ * `list_resources` as the model reads it: PLAIN TEXT, one line per action under one line per
+ * resource. The JSON form it answered until 22.10 repeated every key on every action and escaped
+ * 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.
+ *
+ * ```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.
+ * ```
+ */
+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.`,
+  ];
+  for (const resource of resources) {
+    lines.push('', `${resource.name} — ${oneLine(resource.description)}`);
+    for (const action of resource.actions) {
+      const tags = [
+        action.kind,
+        ...(action.confirms === true ? ['confirms'] : []),
+        ...(action.scope === undefined ? [] : [`scope ${action.scope}`]),
+      ].join('; ');
+      lines.push(`  ${action.name} (${tags}) {${action.params}} — ${oneLine(action.description)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** 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,

package/src/projectable.ts

@@ -4,15 +4,27 @@
 // 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, invoke, isAction } from '@ultimat3/action';
-import { isMcpExposed } from '@ultimat3/core';
+import {
+  guardBeforeInput as actionGuardBeforeInput,
+  actionName,
+  actorOf,
+  invoke,
+  isAction,
+} from '@ultimat3/action';
+import { type Actor, isMcpExposed, useContext } from '@ultimat3/core';
 import type { AnyQuery } from '@ultimat3/query';
-import { isQuery, queryName, sourceFor } from '@ultimat3/query';
+import {
+  isQuery,
+  guardBeforeInput as queryGuardBeforeInput,
+  queryName,
+  sourceFor,
+} from '@ultimat3/query';
 import { asCallerContext } from './caller-context';
 import type { McpExposure, ProjectablePrimitive } from './from-action';
 import { takeIdempotencyKeyArg, withIdempotencyKeyArg } from './idempotency-arg';
-import { toWireSchema } from './input-schema';
+import { toOutputSchema, toRowsOutputSchema, toWireSchema } from './input-schema';
 import type { McpListParams } from './list-params';
+import type { McpToolAnnotations } from './registry';
 
 /**
  * What `defineAppMcp`'s `actions:`/`queries:` accept.
@@ -48,12 +60,21 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
   // `idempotent: true` is honoured on this surface exactly as over HTTP: the caller's key reaches
   // `invoke`, which files it under the action, the caller and the key (`idempotencyKeyFor`).
   const keyed = target.describe().idempotent;
+  const output = toOutputSchema(target.output);
   return {
     name,
     ...(exposure === undefined ? {} : { mcp: exposure }),
     ...(exposure?.description === undefined ? {} : { description: exposure.description }),
     inputJsonSchema: keyed ? withIdempotencyKeyArg(name, wire) : wire,
+    ...(output === undefined ? {} : { outputJsonSchema: output }),
     mutates: true,
+    idempotent: keyed,
+    // The same gate `invoke` opens with, asked by the server before it answers `invalid-args`.
+    admit: (actor: Actor) =>
+      asCallerContext(actor, () => {
+        const ctx = useContext();
+        actionGuardBeforeInput(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
       ? ({ input: args, actor }) => {
@@ -66,12 +87,24 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
 
 export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
   const exposure = exposureOf(target.mcp);
+  // Only a query that DECLARED its rows (`rows: Post.$schema`) has a known answer shape; the tool
+  // answers the rows as a list, so the structured copy is `{ rows }` — `structuredContent` is an
+  // object by the spec.
+  const output = toRowsOutputSchema(target.rows);
+  const name = queryName(target);
   return {
-    name: queryName(target),
+    name,
     ...(exposure === undefined ? {} : { mcp: exposure }),
     ...(exposure?.description === undefined ? {} : { description: exposure.description }),
     inputJsonSchema: toWireSchema(target.input),
+    ...(output === undefined ? {} : { outputJsonSchema: output, outputWrap: 'rows' }),
     mutates: false,
+    // `sourceFor`'s opening gate, on the surface it runs on ('server'), asked before `invalid-args`.
+    admit: (actor: Actor) =>
+      asCallerContext(actor, () => {
+        const ctx = useContext();
+        queryGuardBeforeInput(target.policy, { actor: actorOf(ctx), ctx, query: name }, 'server');
+      }),
     run: ({ input, actor }) =>
       asCallerContext(actor, async () => {
         // `sourceFor` is the authorized front half of `runQuery` — validate, guard, build —
@@ -103,6 +136,8 @@ function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined
     ...(declared.description === undefined ? {} : { description: declared.description }),
     ...(declared.visibleTo === undefined ? {} : { visibleTo: declared.visibleTo }),
     ...(declared.listParams === undefined ? {} : { listParams: declared.listParams }),
+    ...(declared.title === undefined ? {} : { title: declared.title }),
+    ...(declared.annotations === undefined ? {} : { annotations: declared.annotations }),
   };
 }
 
@@ -113,4 +148,6 @@ interface DeclaredMcp {
   readonly visibleTo?: readonly string[];
   /** `QueryMcp` only; an action has no list to compose. */
   readonly listParams?: McpListParams;
+  readonly title?: string;
+  readonly annotations?: McpToolAnnotations;
 }

package/src/registry.ts

@@ -67,6 +67,12 @@ export type ContentBlock =
 export interface McpToolResult {
   readonly content: readonly ContentBlock[];
   readonly isError?: boolean;
+  /**
+   * The same answer as a JSON object, for a client that consumes it programmatically (MCP
+   * 2025-06-18). Set by the projection only when the tool publishes an `outputSchema`, and then it
+   * conforms to it; the text block above still carries the serialized JSON for every other client.
+   */
+  readonly structuredContent?: Readonly<Record<string, unknown>>;
   /**
    * The `X_*` code an `isError` result refused with. AUDIT ONLY — never written to the wire,
    * because the code is already in the rendered body the model reads.
@@ -81,11 +87,45 @@ export interface McpToolResult {
 
 export type ToolArgs = Record<string, unknown>;
 
+/**
+ * MCP's tool annotations (2025-06-18), spelled as the spec spells them. HINTS for a client — which
+ * calls to confirm with a human, which to retry — never a security boundary: the policy, the scope
+ * and the visibility gate decide every call whatever these say.
+ *
+ * The projection derives them from the primitive (`from-action.ts`); an action or query overrides
+ * any of them in its `mcp: { annotations }` block.
+ */
+export interface McpToolAnnotations {
+  /** `true`: the tool changes nothing. A query's default. */
+  readonly readOnlyHint?: boolean;
+  /**
+   * Meaningful only when `readOnlyHint` is false. `true`: it may delete or overwrite. An action's
+   * default is `true` — the spec's own default and the safe one: the framework cannot tell an
+   * additive write from a destructive one, so a client is told to confirm until the author says
+   * otherwise (`annotations: { destructiveHint: false }`).
+   */
+  readonly destructiveHint?: boolean;
+  /** Meaningful only when `readOnlyHint` is false. `true`: a repeat with the same args is a no-op. */
+  readonly idempotentHint?: boolean;
+  /** `true`: it reaches entities outside this app (mail, a payment provider, the web). */
+  readonly openWorldHint?: boolean;
+}
+
 export interface McpTool<A extends ToolArgs = ToolArgs> {
   readonly name: string;
+  /** Display name for a client's UI (MCP 2025-06-18). Absent: the client shows `name`. */
+  readonly title?: string;
   readonly description: string;
   /** The only argument contract. Handed verbatim to the agent by `tools/list`. */
   readonly inputSchema: JsonSchema;
+  /**
+   * The shape of `structuredContent` (MCP 2025-06-18) — a JSON Schema whose root is an object.
+   * Published by `tools/list` only when present; a tool that declares it answers
+   * `structuredContent` conforming to it on every successful call.
+   */
+  readonly outputSchema?: JsonSchema;
+  /** See `McpToolAnnotations`. Published by `tools/list` when present. */
+  readonly annotations?: McpToolAnnotations;
   /** Required scope. Absent = no scope gate (the tool's own policy is the gate). */
   readonly scope?: string;
   /** Who may see and call this tool. Absent = everyone. See `McpVisibility`. */
@@ -107,6 +147,14 @@ export interface McpTool<A extends ToolArgs = ToolArgs> {
    * `list_resources` so an agent plans for the hand-off; it changes nothing about the call.
    */
   readonly confirms?: boolean;
+  /**
+   * The tool's policy, decided on the CALLER alone — throws the same denial `handle` would, or
+   * returns when the caller may call it (or when only the arguments can decide). The server asks
+   * it before answering `invalid-args`, so a caller who may never call this tool gets the 403,
+   * never an issue list describing its arguments. Projected actions and queries and app tools
+   * carry one; a hand-written tool without it answers `invalid-args` as before.
+   */
+  admit?(caller: McpCaller): void;
   // Method syntax (not a property) so a tool declared with narrower args stays assignable.
   handle(args: A, caller: McpCaller): Promise<McpToolResult>;
 }
@@ -116,8 +164,26 @@ export type AnyMcpTool = McpTool<ToolArgs>;
 /** One `tools/list` row — complete and standalone, no follow-up fetch required. */
 export interface ToolListEntry {
   readonly name: string;
+  readonly title?: string;
   readonly description: string;
   readonly inputSchema: JsonSchema;
+  readonly outputSchema?: JsonSchema;
+  readonly annotations?: McpToolAnnotations;
+}
+
+/**
+ * The `tools/list` row of one tool: every optional member attached only when the tool carries it,
+ * so a tool declaring none of them lists exactly the three keys it always did.
+ */
+export function toolListEntry(tool: AnyMcpTool): ToolListEntry {
+  return {
+    name: tool.name,
+    ...(tool.title === undefined ? {} : { title: tool.title }),
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+    ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+  };
 }
 
 /** Rate-limit class of a call. Derived from `destructive`, never declared twice. */
@@ -164,7 +230,13 @@ export type ToolResolution =
   | { readonly kind: 'ok'; readonly tool: AnyMcpTool; readonly args: ToolArgs }
   | { readonly kind: 'not-found'; readonly name: string }
   | { readonly kind: 'scope-denied'; readonly name: string; readonly scope: string }
-  | { readonly kind: 'invalid-args'; readonly name: string; readonly issues: readonly ArgIssue[] };
+  | {
+      readonly kind: 'invalid-args';
+      readonly name: string;
+      readonly issues: readonly ArgIssue[];
+      /** The tool the arguments were refused for — asked to `admit` the caller first. */
+      readonly tool?: AnyMcpTool;
+    };
 
 export class ToolRegistry {
   readonly #tools = new Map<string, AnyMcpTool>();
@@ -198,7 +270,7 @@ export class ToolRegistry {
     const all = [...this.#tools.values()];
     const visible = caller === undefined ? all : all.filter((t) => visibleToCaller(t, caller));
     return visible
-      .map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
+      .map(toolListEntry)
       .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   }
 
@@ -210,7 +282,8 @@ export class ToolRegistry {
    * Both gates then validation, in the only order that is safe:
    *   1. visibility → not-found     (never reveals existence)
    *   2. scope      → scope-denied  (safe: the caller was already shown the tool)
-   *   3. args       → invalid-args
+   *   3. args       → invalid-args — unless the tool's `admit` refuses the caller first, which
+   *                    the server asks before answering (the policy's actor half, `dispatch`)
    *   4. policy     → inside `tool.handle`, which is why it is not here
    * Validating before the gates would leak a schema to a caller that may not see the tool;
    * running the policy before the scope gate would decide a refusal from attacker-supplied
@@ -225,7 +298,7 @@ export class ToolRegistry {
       return { kind: 'scope-denied', name, scope: tool.scope };
     }
     const validation = validateArgs(tool.inputSchema, rawArgs ?? {});
-    if (!validation.ok) return { kind: 'invalid-args', name, issues: validation.issues };
+    if (!validation.ok) return { kind: 'invalid-args', name, issues: validation.issues, tool };
     return { kind: 'ok', tool, args: validation.value };
   }
 
@@ -248,7 +321,10 @@ export function textResult(text: string, isError = false): McpToolResult {
 }
 
 /**
- * JSON payload as a text block — stable 2-space form so an agent can diff two calls.
+ * JSON payload as a text block — COMPACT, one line. Every byte of it lands in the caller's context
+ * window and stays there for the rest of the session; the 2-space form this printed until 22.10
+ * 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
  * straight here, and `JSON.stringify` answers `undefined` for a handler that returned nothing —
@@ -258,14 +334,44 @@ export function textResult(text: string, isError = false): McpToolResult {
  * three-line shape every other expected failure comes back as, and one an agent can act on.
  */
 export function jsonResult(value: unknown): McpToolResult {
-  let text: string | undefined;
+  const text = serialize(value);
+  return text === undefined ? UNSERIALIZABLE : textResult(text);
+}
+
+/**
+ * `jsonResult` plus `structuredContent`, for a tool that publishes an `outputSchema`. The structured
+ * copy is the SERIALIZED value read back — never the value itself — so a `Date` is the string the
+ * text block carries and a class instance is its JSON, exactly what a client validating against the
+ * schema is handed. `wrap` names the key an array answer is published under (`rows` for a query),
+ * because MCP's `structuredContent` is an object.
+ *
+ * An answer whose JSON is not an object (after `wrap`) gets no structured copy: the schema said
+ * object, and a structured copy that contradicts its schema is refused by a validating client.
+ */
+export function structuredResult(value: unknown, wrap?: string): McpToolResult {
+  const text = serialize(value);
+  if (text === undefined) return UNSERIALIZABLE;
+  const parsed: unknown = JSON.parse(text);
+  const structured = wrap === undefined ? parsed : { [wrap]: parsed };
+  if (typeof structured !== 'object' || structured === null || Array.isArray(structured)) {
+    return textResult(text);
+  }
+  return {
+    content: [{ type: 'text', text }],
+    structuredContent: structured as Record<string, unknown>,
+  };
+}
+
+const UNSERIALIZABLE: McpToolResult = textResult(
+  'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — the tool has to return a JSON-serialisable value',
+  true,
+);
+
+/** Compact JSON, `'null'` for a value with no JSON form, `undefined` when serializing threw. */
+function serialize(value: unknown): string | undefined {
   try {
-    text = JSON.stringify(value, null, 2);
+    return JSON.stringify(value) ?? 'null';
   } catch {
-    return textResult(
-      'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — the tool has to return a JSON-serialisable value',
-      true,
-    );
+    return undefined;
   }
-  return textResult(text ?? 'null');
 }

package/src/server-voice.ts

@@ -0,0 +1,64 @@
+// What the server SAYS, per caller, as opposed to what it decides: `initialize`'s `instructions`,
+// the audience every `fix:` line is written for, and the tool result a mistyped argument earns.
+// Split from `server.ts` for the size ceiling; it holds no gate — dispatch stays there.
+
+import { InputInvalidError } from '@ultimat3/action';
+import type { ErrorAudience } from '@ultimat3/core';
+import { formatIssues } from '@ultimat3/schema';
+import type { McpCaller, McpToolResult } from './registry';
+import type { ArgIssue } from './validate-args';
+
+/** See `CreateMcpServerInput.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. */
+export interface McpServerVoice {
+  readonly instructions?: McpInstructions | undefined;
+  readonly errorAudience: ErrorAudience;
+}
+
+/** The instructions THIS caller is handed, or `undefined`. Fail-closed to none, never a throw. */
+export function instructionsFor(
+  instructions: McpInstructions | undefined,
+  caller: McpCaller,
+): string | undefined {
+  if (instructions === undefined) return undefined;
+  let text: unknown;
+  try {
+    text = typeof instructions === 'function' ? instructions(caller) : instructions;
+  } catch {
+    // The handshake is the one call every client makes; advice that failed to render must not
+    // take the connection down with it.
+    return undefined;
+  }
+  return typeof text === 'string' && text.trim() !== '' ? text : undefined;
+}
+
+/**
+ * A tool RESULT for arguments that failed the published schema — not a JSON-RPC error, since
+ * 22.10. Clients surface a protocol error to the human and hide it from the model, so the `-32602`
+ * this answered left the agent nothing to correct and it retried blind. `isError` reaches the
+ * model carrying the same `X_INPUT_INVALID` an HTTP caller gets for the same input, each issue
+ * addressed by path. `-32602` stays for what is not a call at all (no params, a non-string name).
+ */
+export function invalidArgsResult(
+  name: string,
+  issues: readonly ArgIssue[],
+  audience: ErrorAudience,
+): { readonly code: string; readonly result: McpToolResult } {
+  const invalid = new InputInvalidError(
+    name,
+    formatIssues(issues).join('; '),
+    issues.map((issue) => ({
+      path: issue.path,
+      expected: issue.message,
+      received: '',
+      message: issue.message,
+    })),
+    'tool',
+  );
+  return {
+    code: invalid.code,
+    result: { content: [{ type: 'text', text: invalid.format({ audience }) }], isError: true },
+  };
+}