@cyanheads/mcp-ts-core 0.13.7 → 0.13.9

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

@@ -4,18 +4,21 @@
  * @module src/mcp-server/tools/utils/toolHandlerFactory
  */
 import { ZodError, z } from 'zod';
+import { config } from '../../../config/index.js';
 import { readContentStore, readEnrichmentStore } from '../../../core/context.js';
 import { buildHandlerContext, handlerParentContext, resolveHandlerRequest, } from '../../handlerContext.js';
 import { isInputRequiredSignal } 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';
 import { resolvePartialResultKeys } from '../../../utils/formatting/partialResult.js';
 import { asRequestCancelled, ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
-import { measureToolExecution } from '../../../utils/internal/performance.js';
-import { requestContextService } from '../../../utils/internal/requestContext.js';
+import { measureToolExecution, recordToolRejection } from '../../../utils/internal/performance.js';
+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
 // ---------------------------------------------------------------------------
@@ -91,12 +94,13 @@ function renderBranchableTerms(data) {
  * 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
@@ -143,36 +147,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.
@@ -225,7 +284,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,
@@ -238,11 +297,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}`;
 }
@@ -274,30 +330,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) {
@@ -309,18 +480,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
@@ -334,39 +513,80 @@ 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
  * the helper pins the code, message, and `content[]` text a deployment
- * actually produces (#416). Anything that classifies a `ZodError` as
- * `ValidationError` — a handler's own validation, the output-schema parse —
- * is a different failure and does not come through here.
+ * actually produces (#416). A `ZodError` a handler throws from its own
+ * validation classifies as `ValidationError` and does not come through here;
+ * nor does the output-schema parse, which fails as `InternalError`
+ * ({@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
@@ -404,15 +624,29 @@ export function effectiveOutputSchema(def) {
     return def.output.extend(def.enrichment);
 }
 /**
- * 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.
+ * Parses a handler's returned value against the tool's `output` schema. A value
+ * that breaks it fails as `InternalError` naming the tool and the output
+ * contract — a server fault, never the caller's `ValidationError` (#480).
+ * {@link createToolHandler} and the `runToolContract` test helper both route
+ * through it.
+ */
+export function parseToolOutput(def, value) {
+    return parseOutputContract(def.output, value, {
+        kind: 'Tool',
+        name: def.name,
+        contract: 'output',
+    });
+}
+/**
+ * `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,
@@ -439,7 +673,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.');
@@ -624,7 +858,8 @@ function renderEnrichmentTrailer(store, trailer, parsed) {
  *   merged object — keeps enrichment out of the JSON blob and avoids double-render.
  *
  * A required enrichment field the handler never populated fails the parse here,
- * surfacing the authoring bug as a loud error rather than dropping it silently.
+ * surfacing the authoring bug as a loud `InternalError` naming the enrichment
+ * contract rather than dropping it silently (#480).
  */
 export function buildToolSuccessResult(def, ctx, domainValidated, domainContent) {
     if (!def.enrichment) {
@@ -632,10 +867,7 @@ export function buildToolSuccessResult(def, ctx, domainValidated, domainContent)
     }
     const store = readEnrichmentStore(ctx);
     const values = store?.values ?? {};
-    const structuredContent = effectiveOutputSchema(def).parse({
-        ...domainValidated,
-        ...values,
-    });
+    const structuredContent = parseOutputContract(effectiveOutputSchema(def), { ...domainValidated, ...values }, { kind: 'Tool', name: def.name, contract: 'enrichment' });
     const trailer = store && Object.keys(values).length > 0
         ? renderEnrichmentTrailer(store, def.enrichmentTrailer, structuredContent)
         : [];
@@ -679,7 +911,8 @@ function declaredSeverity(def, error) {
  * - Validates input via Zod schema
  * - Measures execution time
  * - Formats response via `format` or JSON default
- * - Catches errors and returns `isError: true`
+ * - 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) {
     // The handler's return value carries no marker, so the arrays partial-success
@@ -692,6 +925,9 @@ export function createToolHandler(def, services, notifiers, inputGate) {
             operation: 'HandleToolRequest',
             additionalContext: { toolName: def.name },
         });
+        // Set once the call reaches the measured region; a failure before it is a
+        // rejection the call and error counters never see (#546).
+        let measured = false;
         try {
             // Check inline auth scopes
             if (def.auth && def.auth.length > 0) {
@@ -713,6 +949,7 @@ export function createToolHandler(def, services, notifiers, inputGate) {
             // merge, and the trailer render all decide the client-visible outcome,
             // so a failure in any of them is a failed call — closing the span when
             // 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);
                 ctx = handlerCtx;
@@ -725,7 +962,7 @@ export function createToolHandler(def, services, notifiers, inputGate) {
                     recordOutput(handlerResult);
                     // Render content[] from the domain payload only (Resolution B), then
                     // merge enrichment into structuredContent and append the content[] trailer.
-                    const validatedResult = def.output.parse(handlerResult);
+                    const validatedResult = parseToolOutput(def, handlerResult);
                     return buildToolSuccessResult(def, handlerCtx, validatedResult, renderToolContent(def, validatedResult, handlerCtx));
                 }
                 catch (error) {
@@ -756,8 +993,39 @@ export function createToolHandler(def, services, notifiers, inputGate) {
                 context: appContext,
                 ...(severity !== undefined && { severity }),
             });
-            return classifyAndBuildToolErrorResult(error);
+            if (!measured)
+                recordToolRejection(def.name, error);
+            const result = classifyAndBuildToolErrorResult(error);
+            if (config.logToolFailurePayloads) {
+                logFailurePayload(services.logger, def.name, appContext, input, result, severity);
+            }
+            return result;
         }
     };
 }
+/**
+ * Writes the opt-in failed-call payload record (#291): the arguments as the
+ * caller sent them — before pre-validation drops or renames a key — and the
+ * `CallToolResult` the client receives, each redacted, serialized, and capped
+ * on its own by `sanitization.serializeForLogging`.
+ *
+ * Logged at the level of the call's own error record and with the same request
+ * context, so the two filter and correlate together. A cancellation writes
+ * nothing: its error record is a routine `info` line, and the caller that would
+ * have read the result is gone.
+ */
+function logFailurePayload(log, toolName, context, input, result, severity) {
+    const { code } = result.structuredContent.error;
+    if (code === JsonRpcErrorCode.RequestCancelled)
+        return;
+    const maxBytes = config.logToolFailurePayloadMaxBytes;
+    const toolInput = sanitization.serializeForLogging(input, maxBytes);
+    const toolResult = sanitization.serializeForLogging(result, maxBytes);
+    log[severity ?? 'error'](`Tool failure payload: ${toolName}`, withExtra(context, {
+        toolInput: toolInput.text,
+        toolInputTruncated: toolInput.truncated,
+        toolResult: toolResult.text,
+        toolResultTruncated: toolResult.truncated,
+    }));
+}
 //# sourceMappingURL=toolHandlerFactory.js.map