@cyanheads/mcp-ts-core 0.13.8 → 0.13.10

package/dist/mcp-server/tools/utils/toolHandlerFactory.js

@@ -5,9 +5,9 @@
  */
 import { ZodError, z } from 'zod';
 import { config } from '../../../config/index.js';
-import { readContentStore, readEnrichmentStore } from '../../../core/context.js';
+import { readContentStore, readEnrichmentStore, resolveDeclaredFailure } from '../../../core/context.js';
 import { buildHandlerContext, handlerParentContext, resolveHandlerRequest, } from '../../handlerContext.js';
-import { isInputRequiredSignal } from '../../inputRequired.js';
+import { CLIENT_CAPABILITY_MISSING_REASON, isInputRequiredSignal, sealThrown, } from '../../inputRequired.js';
 import { parseOutputContract } from '../../outputContract.js';
 import { withRequiredScopes } from '../../transports/auth/lib/authUtils.js';
 import { internalError, JsonRpcErrorCode, McpError, } from '../../../types-global/errors.js';
@@ -17,8 +17,8 @@ import { measureToolExecution, recordToolRejection } from '../../../utils/intern
 import { requestContextService, withExtra, } from '../../../utils/internal/requestContext.js';
 import { sanitization } from '../../../utils/security/sanitization.js';
 import { ATTR_MCP_TOOL_ENRICHED } from '../../../utils/telemetry/attributes.js';
-import { countCoerced, prevalidateToolArguments, repairRepresentations, } from './inputPrevalidation.js';
-import { isZodObjectSchema } from './schemaShape.js';
+import { countCoerced, prevalidateAliasFirst, prevalidateToolArguments, recordPrevalidation, repairRepresentations, } from './inputPrevalidation.js';
+import { isZodObjectSchema, zodDef } from './schemaShape.js';
 // ---------------------------------------------------------------------------
 // Default formatter
 // ---------------------------------------------------------------------------
@@ -62,15 +62,17 @@ function extractRecoveryHint(data) {
 /**
  * The compact trailing line carrying the two `data` fields a caller branches
  * on — `reason`, the stable identifier, and `retryable`, whether a retry can
- * succeed (#458). Both reach `structuredContent.error.data`; without this line
- * neither reaches the text surface, so a model that just failed cannot tell a
- * deterministic rejection from a transient one.
+ * succeed (#458) — then `request <id>`, the `data.requestId` the server's log
+ * records carry (#576). All three reach `structuredContent.error.data`;
+ * without this line none reaches the text surface, so a model that just failed
+ * cannot tell a deterministic rejection from a transient one, and a failure
+ * reported from a `content[]`-only client cannot be matched to its log record.
  *
- * Returns `undefined` when `data` carries neither — a classified plain
- * `Error`, an `McpError` with no `data` — leaving the text as it was. The
- * numeric `code` and `data.issues` stay JSON-only on purpose: the code is the
- * one envelope field a model cannot act on, and the message already renders
- * each issue as a sentence.
+ * Returns `undefined` when `data` carries none of them — an `McpError` with no
+ * `data` outside a request, as `runToolContract` builds it — leaving the text
+ * as it was. The numeric `code` and `data.issues` stay JSON-only on purpose:
+ * the code is the one envelope field a model cannot act on, and the message
+ * already renders each issue as a sentence.
  */
 function renderBranchableTerms(data) {
     const terms = [];
@@ -80,6 +82,9 @@ function renderBranchableTerms(data) {
     if (typeof data?.retryable === 'boolean') {
         terms.push(data.retryable ? 'retryable' : 'not retryable');
     }
+    if (typeof data?.requestId === 'string' && data.requestId.length > 0) {
+        terms.push(`request ${data.requestId}`);
+    }
     return terms.length > 0 ? `(${terms.join(' · ')})` : undefined;
 }
 /**
@@ -89,17 +94,18 @@ function renderBranchableTerms(data) {
  * - `structuredContent.error` — read by clients like Claude Code (JSON)
  *
  * The text carries the message, the `data.recovery.hint` when it adds
- * something, and the branchable `reason` / `retryable` terms
- * {@link renderBranchableTerms} renders; the numeric `code` and `data.issues`
- * stay JSON-only.
+ * something, and the `reason` / `retryable` / `request` terms
+ * {@link renderBranchableTerms} renders, in that order; the numeric `code` and
+ * `data.issues` stay JSON-only.
  *
  * The `Recovery:` line is dropped when the message already contains the hint
- * verbatim (#459) — `buildArgumentRecoveryHint` falls back to an issue's own
- * message for a constraint or refinement, and repeating that sentence costs
- * the reader without adding a next step. Containment, not equality: the
- * argument-rejection preamble and a field-path prefix both leave the hint's
- * whole text on screen. `structuredContent.error.data.recovery.hint` stays
- * populated either way, so #445's guarantee holds on the JSON surface.
+ * verbatim (#459) — `buildArgumentRecoveryHint` restates a constraint or
+ * refinement issue as its own message line, and a hint made only of those is
+ * the message's issue text, so repeating it costs the reader without adding a
+ * next step. Containment, not equality: the argument-rejection preamble leaves
+ * that text whole on screen, and so does a handler hint the message embeds.
+ * `structuredContent.error.data.recovery.hint` stays populated either way, so
+ * #445's guarantee holds on the JSON surface.
  *
  * Note: `_meta.error` is intentionally NOT emitted — the error code, message,
  * and data live on `structuredContent.error` instead, mirroring the success
@@ -146,36 +152,91 @@ const ABSENT = Symbol('absent');
  * is how Zod itself reads it.
  */
 function readArgumentAt(args, path) {
-    let cursor = args;
-    for (const segment of path) {
-        if (cursor === null || typeof cursor !== 'object')
-            return ABSENT;
-        if (!Object.hasOwn(cursor, segment))
-            return ABSENT;
-        cursor = cursor[segment];
-    }
-    return cursor === undefined ? ABSENT : cursor;
+    const value = path.reduce(stepInto, args);
+    return value === undefined ? ABSENT : value;
+}
+/** The caller's value one step down, or `undefined` when nothing owns one there. */
+function stepInto(value, step) {
+    return value !== null && typeof value === 'object' && Object.hasOwn(value, step)
+        ? value[step]
+        : undefined;
 }
 /** The accepted-value half of an `invalid_value` sentence, from the issue's own values. */
 function expectedValuesText(values) {
     const rendered = values.map((value) => JSON.stringify(value)).join('|');
     return values.length === 1 ? `Expected ${rendered}` : `Expected one of ${rendered}`;
 }
+/** The branch's only issue, when it has exactly one. */
+function onlyIssue(branch) {
+    return branch.length === 1 ? branch[0] : undefined;
+}
+/** Whether any of a branch's issues names a path below the branch's root. */
+function failsBelowRoot(branch) {
+    return branch.some((issue) => issue.path.length > 0);
+}
 /**
- * The union branches worth rendering: every branch except one whose only issue
- * is a single-valued `invalid_value`.
+ * The union branches worth rendering. Two filters, both reading issue shape
+ * only, never message text:
  *
- * That shape is the `z.literal('')` blank-field sentinel of the form-client
- * convention — never the branch that says what would have been accepted. The
- * filter reads issue shape only, never message text, so a one-entry
- * `z.enum([...])` (which Zod reports identically) is filtered too and the
- * caller falls back to the union's own message.
+ * - **#417** — drop a branch whose only issue is a single-valued
+ *   `invalid_value`. That shape is the `z.literal('')` blank-field sentinel of
+ *   the form-client convention — never the branch that says what would have
+ *   been accepted. A one-entry `z.enum([...])`, which Zod reports identically,
+ *   is filtered too, and the caller falls back to the union's own message.
+ * - **#492** — once some branch fails below its root, drop every branch whose
+ *   only issue is a root `invalid_type`. In a one-or-many field
+ *   (`z.union([z.array(Item), Item])`) that branch merely says the value is
+ *   the other shape; the branch that failed inside the value is the one that
+ *   says what to change. When every branch fails at its root, none is dropped.
  */
 function selectUnionBranches(branches) {
-    return branches.filter((branch) => {
-        const only = branch.length === 1 ? branch[0] : undefined;
+    const selected = branches.filter((branch) => {
+        const only = onlyIssue(branch);
         return !(only?.code === 'invalid_value' && only.values.length === 1);
     });
+    if (!selected.some(failsBelowRoot))
+        return selected;
+    return selected.filter((branch) => {
+        const only = onlyIssue(branch);
+        return !(only?.code === 'invalid_type' && only.path.length === 0);
+    });
+}
+/**
+ * The issues a rejection renders, in order: Zod's list, except that a union
+ * left with one selected branch that fails below its root is replaced by that
+ * branch's issues under the union's path (#492) — so a one-or-many field
+ * reports a list element's field error exactly as a list-only field does
+ * (`items.1.name: …`). Recursive, so a one-or-many union nested in another, or
+ * inside a list element, resolves the same way at every level.
+ *
+ * The message ({@link formatInputValidationMessage}) and the hint
+ * ({@link buildArgumentRecoveryHint}) both render from this list, which keeps
+ * the hint's restatements identical to the message's lines. `data.issues` is
+ * never rebuilt from it: it ships Zod's own list.
+ */
+function renderedIssues(issues, prefix = []) {
+    return issues.flatMap((issue) => {
+        const path = [...prefix, ...issue.path];
+        if (issue.code === 'invalid_union') {
+            const [branch, ...others] = selectUnionBranches(issue.errors);
+            if (branch && others.length === 0 && failsBelowRoot(branch)) {
+                return renderedIssues(branch, path);
+            }
+        }
+        return [{ issue, path }];
+    });
+}
+/** `items.1.name` — the dotted form a path takes in the message and the hint. */
+function dottedPath(path) {
+    return path.map(String).join('.');
+}
+/**
+ * One line of the rendered detail: `path: message`, or the bare message at the
+ * root. `args` decides the absent/present bit {@link renderIssueMessage} reads.
+ */
+function renderIssueLine({ issue, path }, args) {
+    const message = renderIssueMessage(issue, readArgumentAt(args, path) === ABSENT);
+    return path.length > 0 ? `${dottedPath(path)}: ${message}` : message;
 }
 /**
  * The readable half of one issue's rendered line.
@@ -228,7 +289,7 @@ function renderIssueMessage(issue, absent) {
  */
 function renderBranchIssue(issue, absent) {
     const message = renderIssueMessage(issue, absent);
-    return issue.path.length > 0 ? `${issue.path.map(String).join('.')}: ${message}` : message;
+    return issue.path.length > 0 ? `${dottedPath(issue.path)}: ${message}` : message;
 }
 /**
  * Renders an argument-validation failure the way the MCP SDK renders its own,
@@ -241,11 +302,8 @@ function renderBranchIssue(issue, absent) {
  * {@link readArgumentAt}; see {@link renderIssueMessage} for what that decides.
  */
 export function formatInputValidationMessage(toolName, error, args) {
-    const detail = error.issues
-        .map((issue) => {
-        const message = renderIssueMessage(issue, readArgumentAt(args, issue.path) === ABSENT);
-        return issue.path.length > 0 ? `${issue.path.map(String).join('.')}: ${message}` : message;
-    })
+    const detail = renderedIssues(error.issues)
+        .map((entry) => renderIssueLine(entry, args))
         .join(', ');
     return `Input validation error: Invalid arguments for tool ${toolName}: ${detail}`;
 }
@@ -277,30 +335,145 @@ function joinNames(names) {
 function rootPropertyNames(input) {
     return isZodObjectSchema(input) ? Object.keys(input.shape) : [];
 }
+/**
+ * The `z.object()` a nested unknown-key issue sits in, found by walking its
+ * rendered path down from `schema` beside the caller's own `value` — or
+ * `undefined` when the path does not land on exactly one object (#566).
+ *
+ * Wrappers (`optional`, `nullable`, `default`, …), `pipe`, and `z.lazy()` are
+ * looked through. A numeric step enters an array element or tuple item; a
+ * string step, a property or a record value. A discriminated union follows the
+ * variant the argument's own discriminator selects, as Zod did. A plain union
+ * follows the one option under which the rest of the path still lands on an
+ * object — the branch {@link renderedIssues} lifted under #492. Anything else,
+ * an intersection or a union two options satisfy, resolves to nothing.
+ */
+function objectSchemaAt(schema, path, value) {
+    const def = zodDef(schema);
+    if (!def)
+        return undefined;
+    if (def.type === 'lazy' && def.getter)
+        return objectSchemaAt(def.getter(), path, value);
+    if (def.type === 'pipe')
+        return objectSchemaAt(def.in, path, value);
+    if (def.innerType !== undefined)
+        return objectSchemaAt(def.innerType, path, value);
+    if (def.type === 'union')
+        return unionOptionAt(def, path, value);
+    const [step, ...rest] = path;
+    if (step === undefined)
+        return isZodObjectSchema(schema) ? schema : undefined;
+    const next = stepInto(value, step);
+    switch (def.type) {
+        case 'object':
+            return typeof step === 'string' && def.shape && Object.hasOwn(def.shape, step)
+                ? objectSchemaAt(def.shape[step], rest, next)
+                : undefined;
+        case 'record':
+            return objectSchemaAt(def.valueType, rest, next);
+        case 'array':
+            return typeof step === 'number' ? objectSchemaAt(def.element, rest, next) : undefined;
+        case 'tuple':
+            return typeof step === 'number'
+                ? objectSchemaAt(def.items?.[step] ?? def.rest, rest, next)
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+/** {@link objectSchemaAt} at a union: the one option the path resolves through. */
+function unionOptionAt(def, path, value) {
+    const options = def.options ?? [];
+    const { discriminator } = def;
+    if (typeof discriminator === 'string') {
+        const tag = stepInto(value, discriminator);
+        const selected = options.find((option) => {
+            const field = isZodObjectSchema(option) ? option.shape[discriminator] : undefined;
+            return field?.safeParse(tag).success === true;
+        });
+        return selected === undefined ? undefined : objectSchemaAt(selected, path, value);
+    }
+    const resolved = options.flatMap((option) => objectSchemaAt(option, path, value) ?? []);
+    return resolved.length === 1 ? resolved[0] : undefined;
+}
+/**
+ * The unknown-key sentence for one `unrecognized_keys` issue.
+ *
+ * A root key names the root properties the tool advertises (#445). A key inside
+ * a nested strict object is named by its full path, beside the keys that object
+ * accepts (#566) — the root list there would send the caller to move the key to
+ * the root or rename it after a root field. Neither list is given when there is
+ * none to give: a discriminated-union root, a nested object declaring no keys,
+ * or a path {@link objectSchemaAt} cannot resolve.
+ */
+function unknownKeySentence(input, keys, path, args) {
+    const label = keys.length === 1 ? 'Unknown key' : 'Unknown keys';
+    if (path.length === 0) {
+        const accepted = rootPropertyNames(input);
+        return accepted.length > 0
+            ? `${label} ${keys.join(', ')}. This tool accepts: ${accepted.join(', ')}.`
+            : `${label} ${keys.join(', ')}.`;
+    }
+    const where = dottedPath(path);
+    const named = keys.map((key) => `${where}.${key}`).join(', ');
+    const accepted = Object.keys(objectSchemaAt(input, path, args)?.shape ?? {});
+    return accepted.length > 0
+        ? `${label} ${named}. ${where} accepts: ${accepted.join(', ')}.`
+        : `${label} ${named}.`;
+}
+/**
+ * The wrong-type sentence for one `invalid_type` issue.
+ *
+ * `int` is the one expectation a JSON number fails by type — `.int()`,
+ * `z.int()`, `z.int32()`, and `z.uint32()` all report it, while range and
+ * safe-integer violations arrive as `too_big` / `too_small` — so a number
+ * arriving there has a fractional part, and the sentence names that fix
+ * rather than the type names `int` and `number`, which the value already
+ * satisfies (#499).
+ */
+function wrongTypeSentence(subject, expected, arrived) {
+    if (arrived === ABSENT)
+        return `Send ${subject} as ${withArticle(expected)}.`;
+    if (expected === 'int' && typeof arrived === 'number') {
+        return `Send ${subject} as an integer, not a fractional number.`;
+    }
+    return `Send ${subject} as ${withArticle(expected)}, not ${arrivedTypeText(arrived)}.`;
+}
 /**
  * Synthesizes `data.recovery.hint` from the Zod issues, the raw arguments, and
  * the root schema (#445) — so the one failure a weaker model hits most often
  * carries the same next step every handler-thrown error does, instead of
  * costing a round trip for the schema.
  *
- * One sentence per issue, joined into a single hint, except that every missing
- * required field collapses into one `Provide …` sentence at the first of their
- * positions. An issue no bucket claims contributes its rendered message
- * unchanged, which keeps the hint nonempty for any rejection Zod can produce.
+ * One sentence per {@link renderedIssues} entry, joined into a single hint,
+ * except that every missing required field collapses into one `Provide …`
+ * sentence at the first of their positions. An issue no bucket claims is
+ * restated as its message line — `start: Must be …`, path included, so
+ * identical constraints on different fields stay distinguishable (#493).
+ *
+ * When every sentence is a restatement, the hint is the message's issue text
+ * verbatim, which is what lets {@link buildToolErrorResult} drop the
+ * `Recovery:` line (#459). When restatements share the hint with the
+ * framework's own sentences, each is terminated so it cannot run into the next
+ * one, and a sentence already stated is not repeated.
+ *
+ * `report` closes the hint with what the pre-validation step changed before
+ * the parse (#468) — `Validated query as targetQuery.` for a rewritten key,
+ * `Dropped undeclared key _max.` for an underscore-rule drop — since the issues
+ * name only the keys that were validated. Both are framework sentences, never
+ * restatements, so a hint carrying one keeps its `Recovery:` line.
  */
-function buildArgumentRecoveryHint(def, error, args) {
+function buildArgumentRecoveryHint(def, error, args, report) {
     const sentences = [];
+    const restatements = [];
     const missing = [];
     let missingSlot = -1;
-    for (const issue of error.issues) {
-        const path = issue.path.map(String).join('.');
-        const arrived = readArgumentAt(args, issue.path);
+    for (const entry of renderedIssues(error.issues)) {
+        const { issue } = entry;
+        const path = dottedPath(entry.path);
+        const arrived = readArgumentAt(args, entry.path);
         if (issue.code === 'unrecognized_keys') {
-            const label = issue.keys.length === 1 ? 'Unknown key' : 'Unknown keys';
-            const accepted = rootPropertyNames(def.input);
-            sentences.push(accepted.length > 0
-                ? `${label} ${issue.keys.join(', ')}. This tool accepts: ${accepted.join(', ')}.`
-                : `${label} ${issue.keys.join(', ')}.`);
+            sentences.push(unknownKeySentence(def.input, issue.keys, entry.path, args));
             continue;
         }
         if (path.length > 0 && arrived === ABSENT) {
@@ -312,18 +485,26 @@ function buildArgumentRecoveryHint(def, error, args) {
             continue;
         }
         if (issue.code === 'invalid_type') {
-            const subject = path.length > 0 ? path : 'the arguments';
-            const expected = withArticle(issue.expected);
-            sentences.push(arrived === ABSENT
-                ? `Send ${subject} as ${expected}.`
-                : `Send ${subject} as ${expected}, not ${arrivedTypeText(arrived)}.`);
+            sentences.push(wrongTypeSentence(path.length > 0 ? path : 'the arguments', issue.expected, arrived));
             continue;
         }
-        sentences.push(renderIssueMessage(issue, false));
+        const line = renderIssueLine(entry, args);
+        restatements.push(line);
+        sentences.push(terminateSentence(line));
+    }
+    if (report && report.aliased.length > 0) {
+        const rewrites = report.aliased.map(({ alias, target }) => `${alias} as ${target}`);
+        sentences.push(`Validated ${joinNames(rewrites)}.`);
     }
+    if (report && report.ignored.length > 0) {
+        const label = report.ignored.length === 1 ? 'key' : 'keys';
+        sentences.push(`Dropped undeclared ${label} ${joinNames(report.ignored)}.`);
+    }
+    if (restatements.length === sentences.length)
+        return restatements.join(', ');
     if (missingSlot >= 0)
         sentences[missingSlot] = `Provide ${joinNames(missing)}.`;
-    return sentences.join(' ');
+    return [...new Set(sentences)].join(' ');
 }
 /**
  * Validates raw tool arguments against the definition's `input` schema, or
@@ -337,10 +518,22 @@ function buildArgumentRecoveryHint(def, error, args) {
  * An ordered pre-validation step wraps the parse. Before it,
  * {@link prevalidateToolArguments} drops client-added keys (#453) and rewrites
  * key aliases (#452); after a failure — and only then —
- * {@link repairRepresentations} undoes a stringified array and the arguments
- * are parsed once more (#234), the repair kept only if the author's own schema
- * now accepts it. When nothing validates, the *original* rejection is thrown
- * verbatim, built from the arguments that produced it.
+ * {@link repairRepresentations} undoes a stringified array or object or an
+ * integer sent for a string, and the arguments are parsed once more (#234,
+ * #479, #487), the repair kept only if the author's own schema now accepts it.
+ * When that attempt still fails and its drop discarded a key,
+ * {@link prevalidateAliasFirst} reruns the stages alias-first and the same
+ * parse-then-repair runs on the result, kept only if it validates (#563).
+ * {@link recordPrevalidation} then counts and logs the attempt the handler
+ * receives, so a call the first attempt validates is untouched by the retry.
+ * When nothing validates, the *original* rejection of the last attempt is
+ * thrown — the retry's when it ran, since there every key the drop discarded
+ * reached its target and the issues name what is wrong with the value it
+ * carried — built from the arguments that produced it, identical to the one
+ * the same call gets under `input: { coerce: false }`. It carries the rewrites
+ * and underscore-rule drops that attempt made as `data.input`, and as
+ * sentences closing the hint (#468); a call with neither gains no
+ * `data.input`.
  *
  * The single argument-rejection path. {@link createToolHandler} and the
  * `runToolContract` test helper both route through it, so a test written to
@@ -351,44 +544,88 @@ function buildArgumentRecoveryHint(def, error, args) {
  * ({@link parseToolOutput}).
  */
 export function parseToolArguments(def, input, options = {}) {
-    const prepared = prevalidateToolArguments(def, input, options.input, options.context);
-    const parsed = def.input.safeParse(prepared);
+    const first = prevalidateToolArguments(def, input, options.input);
+    const parsed = parseAttempt(def, first.args, options.input);
     if (parsed.success)
-        return parsed.data;
-    if (options.input?.coerce !== false) {
-        const repaired = repairRepresentations(prepared, parsed.error.issues);
-        if (repaired !== prepared) {
-            const retried = def.input.safeParse(repaired);
-            if (retried.success) {
-                countCoerced(def.name, options.context);
-                return retried.data;
-            }
-        }
+        return accept(def, first, parsed, options.context);
+    let rejected = { attempt: first, error: parsed.error };
+    const retry = prevalidateAliasFirst(def, input, first, options.input);
+    if (retry) {
+        const retried = parseAttempt(def, retry.args, options.input);
+        if (retried.success)
+            return accept(def, retry, retried, options.context);
+        rejected = { attempt: retry, error: retried.error };
     }
-    throw new McpError(JsonRpcErrorCode.InvalidParams, formatInputValidationMessage(def.name, parsed.error, prepared), {
-        issues: parsed.error.issues,
+    const { attempt, error } = rejected;
+    recordPrevalidation(def, attempt, options.context);
+    const { report } = attempt;
+    throw new McpError(JsonRpcErrorCode.InvalidParams, formatInputValidationMessage(def.name, error, attempt.args), {
+        issues: error.issues,
         reason: INVALID_ARGUMENTS_REASON,
-        recovery: { hint: buildArgumentRecoveryHint(def, parsed.error, prepared) },
+        ...(report && { input: report }),
+        recovery: { hint: buildArgumentRecoveryHint(def, error, attempt.args, report) },
     });
 }
+/**
+ * Parses one attempt's arguments, and on failure repairs them once and
+ * re-parses, keeping the repair only if the schema then accepts it. A failure
+ * carries the first parse's error: a discarded repair leaves no trace.
+ */
+function parseAttempt(def, args, options) {
+    const parsed = def.input.safeParse(args);
+    if (parsed.success)
+        return { success: true, data: parsed.data, coerced: [] };
+    if (options?.coerce !== false) {
+        const repair = repairRepresentations(args, parsed.error.issues);
+        if (repair.args !== args) {
+            const retried = def.input.safeParse(repair.args);
+            if (retried.success)
+                return { success: true, data: retried.data, coerced: repair.kinds };
+        }
+    }
+    return { success: false, error: parsed.error };
+}
+/** Emits the winning attempt's telemetry and hands its arguments to the handler. */
+function accept(def, attempt, parsed, context) {
+    recordPrevalidation(def, attempt, context);
+    if (parsed.coerced.length > 0)
+        countCoerced(def.name, parsed.coerced, context);
+    return parsed.data;
+}
 /**
  * Builds an error `CallToolResult` from a raw thrown value. Classifies via
  * {@link ErrorHandler.classifyOnly} when the value isn't already an
  * `McpError`. Only propagates data from `McpError` (its declared `data`) or
- * `ZodError` (its `issues`) — other thrown values get a `structuredContent.error`
- * with `code` and `message` only, so internal classification context never
- * leaks to clients.
+ * `ZodError` (its `issues`), so internal classification context never leaks
+ * to clients.
+ *
+ * `requestId`, when given, is set as `data.requestId` on the envelope — after
+ * the thrown data, so the framework's value replaces a thrown one, as
+ * canonical fields win in log records (#550) — and closes the `content[]`
+ * terms line (#576). It is the one request-context field that reaches `data`,
+ * added here rather than to the thrown `McpError.data`, so the error the
+ * handler threw and the log record's `errorData` stay context-free (#548).
+ * `runToolContract` passes none: it has no real request, so a thrown
+ * `data.requestId` is dropped rather than rendered as one.
  *
  * Use after invoking {@link ErrorHandler.handleError} for OTel/logging side
  * effects — this helper does not log.
  */
-export function classifyAndBuildToolErrorResult(error) {
+export function classifyAndBuildToolErrorResult(error, requestId) {
+    const withRequestId = (data) => {
+        if (requestId !== undefined)
+            return { ...data, requestId };
+        if (data?.requestId === undefined)
+            return data;
+        const { requestId: _thrown, ...rest } = data;
+        return Object.keys(rest).length > 0 ? rest : undefined;
+    };
     if (error instanceof McpError) {
-        return buildToolErrorResult(error.code, error.message, error.data);
+        return buildToolErrorResult(error.code, error.message, withRequestId(error.data));
     }
     const { code, message } = ErrorHandler.classifyOnly(error);
     const data = error instanceof ZodError ? { issues: error.issues } : undefined;
-    return buildToolErrorResult(code, message, data);
+    return buildToolErrorResult(code, message, withRequestId(data));
 }
 // ---------------------------------------------------------------------------
 // Success response shaping — enrichment merge + trailer
@@ -422,15 +659,15 @@ export function parseToolOutput(def, value) {
     });
 }
 /**
- * A contract entry's `when` text, terminated so the entry that follows it —
- * and the description's own trailing sentence — starts a new one (#389).
- * Nothing validates a punctuation convention on `when`, and an entry authored
- * as a fragment otherwise runs into whatever comes next. Punctuating at the
- * join leaves the authored text alone, terminator or not.
+ * `text`, trimmed and ending in terminal punctuation, so whatever is joined
+ * after it starts a new sentence. Punctuating at the join leaves authored text
+ * alone, terminator or not: a contract entry's `when` (#389), which nothing
+ * validates a punctuation convention on, and an issue message restated in an
+ * argument hint beside the framework's own sentences (#493).
  */
-function terminateWhen(when) {
-    const text = when.trim();
-    return /[.?!]$/.test(text) ? text : `${text}.`;
+function terminateSentence(text) {
+    const trimmed = text.trim();
+    return /[.?!]$/.test(trimmed) ? trimmed : `${trimmed}.`;
 }
 /**
  * The error envelope a tool can put on `structuredContent` when it fails,
@@ -457,7 +694,7 @@ function toolErrorEnvelopeSchema(def) {
         ? z
             .string()
             .describe(`Machine-readable failure mode. Declared by this tool: ${contract
-            .map((entry) => `\`${entry.reason}\`: ${terminateWhen(entry.when)}`)
+            .map((entry) => `\`${entry.reason}\`: ${terminateSentence(entry.when)}`)
             .join(' ')} Other values are possible when a failure originates below the handler.`)
             .meta({ examples: reasons })
         : z.string().describe('Machine-readable failure mode.');
@@ -664,25 +901,37 @@ export function buildToolSuccessResult(def, ctx, domainValidated, domainContent)
 // Factory
 // ---------------------------------------------------------------------------
 /**
- * The log level the definition declared for the failure that just unwound, or
- * `undefined` to keep `error` (#380).
+ * The two reasons the framework raises itself, both a refusal of the call
+ * rather than a fault in this server: `invalid_arguments`, only from the schema
+ * gate in {@link parseToolArguments}, and `client_capability_missing`, only
+ * from `ctx.requestInput`'s capability gate.
+ */
+const FRAMEWORK_REFUSAL_REASONS = new Set([
+    INVALID_ARGUMENTS_REASON,
+    CLIENT_CAPABILITY_MISSING_REASON,
+]);
+/**
+ * The level the `Error in tool:<name>` record is emitted at, or `undefined` to
+ * keep `error`.
  *
- * The outer catch is the one place holding both the definition and the thrown
- * error, so the reason-to-entry lookup happens here rather than inside
- * `ErrorHandler`, which sees neither. Resolution is deliberately narrow: an
- * `McpError` whose `data.reason` names a contract entry that declared a
- * severity. A plain `Error`, a reason thrown below the handler that the
- * contract never declared, and an entry with no severity all fall through to
- * today's behavior. A cancellation is settled earlier — `asRequestCancelled`
- * replaces the thrown value, so no declared reason reaches this point.
+ * A severity the matched `errors[]` entry declares wins (#380). Otherwise one
+ * of the framework's own refusals ({@link FRAMEWORK_REFUSAL_REASONS}) logs at
+ * `notice` (#567): a caller's arguments failing the tool's schema, or a client
+ * connection that cannot serve an input request, is routine traffic, and a
+ * schema that wrongly rejects valid calls still shows per tool on
+ * `mcp.tool.rejections`. Everything else — a plain `Error`, an undeclared
+ * reason, an entry with no severity, an auth refusal, an output-contract
+ * failure — keeps `error`. A cancellation takes `handleError`'s own `info`
+ * path whatever this returns.
+ *
+ * Resolved here rather than in `ErrorHandler`, which also serves services,
+ * prompts, and transports and knows neither the definition nor the schema gate.
  */
-function declaredSeverity(def, error) {
-    if (!(error instanceof McpError))
-        return undefined;
-    const reason = error.data?.reason;
-    if (typeof reason !== 'string')
-        return undefined;
-    return def.errors?.find((entry) => entry.reason === reason)?.severity;
+function failureSeverity(entry, failure) {
+    if (entry?.severity !== undefined)
+        return entry.severity;
+    const reason = failure instanceof McpError ? failure.data?.reason : undefined;
+    return typeof reason === 'string' && FRAMEWORK_REFUSAL_REASONS.has(reason) ? 'notice' : undefined;
 }
 /**
  * Creates an MCP tool handler from a tool definition.
@@ -698,14 +947,14 @@ function declaredSeverity(def, error) {
  * - Catches errors and returns `isError: true`, counting one raised before the
  *   measured region (the scope check, argument validation) on `mcp.tool.rejections`
  */
-export function createToolHandler(def, services, notifiers, inputGate) {
+export function createToolHandler(def, services, notifiers, capabilities) {
     // The handler's return value carries no marker, so the arrays partial-success
     // telemetry reads are named by the output schema — resolved once here (#524).
     const partialResultKeys = resolvePartialResultKeys(def.output.shape);
     return async (input, serverContext) => {
         const request = resolveHandlerRequest(serverContext, services, notifiers);
         const appContext = requestContextService.createRequestContext({
-            parentContext: handlerParentContext(request),
+            parentContext: handlerParentContext(serverContext),
             operation: 'HandleToolRequest',
             additionalContext: { toolName: def.name },
         });
@@ -735,7 +984,7 @@ export function createToolHandler(def, services, notifiers, inputGate) {
             // the handler returned recorded those as successes (#346).
             measured = true;
             return await measureToolExecution(async (spanContext, recordOutput) => {
-                const handlerCtx = buildHandlerContext(request, services, spanContext, def.errors, inputGate);
+                const handlerCtx = buildHandlerContext(request, services, spanContext, def.errors, capabilities);
                 ctx = handlerCtx;
                 try {
                     // Handler may return sync or async.
@@ -752,8 +1001,10 @@ export function createToolHandler(def, services, notifiers, inputGate) {
                 catch (error) {
                     // Inside the measurement on purpose: the completion log's
                     // `metrics.errorCode` and the span's error-code attribute are
-                    // derived from what leaves this callback (#421).
-                    throw asRequestCancelled(error, request.signal);
+                    // derived from what leaves this callback (#421). An input-required
+                    // signal leaves with its `requestState` sealed when a key is
+                    // configured, so a sealing failure is a failed call like any other.
+                    throw asRequestCancelled(await sealThrown(error, services.requestState, serverContext), request.signal);
                 }
             }, { ...appContext, toolName: def.name }, validatedInput, () => {
                 const store = ctx ? readEnrichmentStore(ctx) : undefined;
@@ -764,22 +1015,28 @@ export function createToolHandler(def, services, notifiers, inputGate) {
         }
         catch (error) {
             // `ctx.requestInput(...)` is protocol control flow, not a failure: return
-            // the `input_required` result untouched, with no span, log, or
-            // classification. The client (2026 era) or the SDK's legacy shim (2025
-            // era) fulfils it and re-invokes this handler. A request this connection
-            // cannot serve never reaches here as a signal — `ctx.requestInput`
-            // throws the refusal instead, and it arrives below as an `McpError`.
+            // the `input_required` result — its `requestState` already sealed when a
+            // key is configured — with no span, log, or classification. The client
+            // (2026 era) or the SDK's legacy shim (2025 era) fulfils it and
+            // re-invokes this handler. A request this connection cannot serve never
+            // reaches here as a signal — `ctx.requestInput` throws the refusal
+            // instead, and it arrives below as an `McpError`.
             if (isInputRequiredSignal(error))
                 return error.result;
-            const severity = declaredSeverity(def, error);
-            ErrorHandler.handleError(error, {
+            // One reason-to-entry lookup: the declared recovery fills a failure that
+            // carries none (#579) and the entry's severity sets the log level (#380,
+            // #567). Filled before `handleError`, so the error record, the envelope,
+            // and the failure-payload record carry the same hint.
+            const { entry, failure } = resolveDeclaredFailure(def.errors, error);
+            const severity = failureSeverity(entry, failure);
+            ErrorHandler.handleError(failure, {
                 operation: `tool:${def.name}`,
                 context: appContext,
                 ...(severity !== undefined && { severity }),
             });
             if (!measured)
-                recordToolRejection(def.name, error);
-            const result = classifyAndBuildToolErrorResult(error);
+                recordToolRejection(def.name, failure);
+            const result = classifyAndBuildToolErrorResult(failure, appContext.requestId);
             if (config.logToolFailurePayloads) {
                 logFailurePayload(services.logger, def.name, appContext, input, result, severity);
             }