@effected/mcp 0.2.0 → 0.4.0

package/McpHarness.js

@@ -2,7 +2,7 @@ import { ToolFailure } from "./ToolFailure.js";
 import { DEFAULT_CLIENT_INFO, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame, requestKey } from "./internal/wire.js";
 import { McpTestFailure } from "./McpTestFailure.js";
 import { Console, Deferred, Effect, Exit, Layer, Queue, Sink, Stdio, Stream } from "effect";
-import { McpProtocol } from "effect/unstable/ai";
+import { McpProtocol } from "effect/ai";
 
 //#region src/McpHarness.ts
 /**
@@ -38,11 +38,27 @@ import { McpProtocol } from "effect/unstable/ai";
 *   anything that went through `console.log`, which in a real server is
 *   the wire. Assert it empty.
 * - On a stateful revision (the default `2025-11-25`), send `initialize`
-*   first. Every other request before it fails with `NotInitialized` and
-*   is never written, `ping` included: the server would only answer an
-*   opaque refusal, `-32602 Invalid request metadata` when a stateless
-*   adapter is listed first (as in `McpStdio.protocols`), or
-*   `-32603 Internal error` when only stateful revisions are served.
+*   first. `ping` is the exception: the server answers it `{}` before
+*   initialization, so it is written. Every other request before
+*   `initialize` fails with `NotInitialized` and is never written: the
+*   server would only answer an opaque refusal,
+*   `-32602 Invalid request metadata` when a stateless adapter is listed
+*   first (as in `McpStdio.protocols`), or `-32603 Internal error` when
+*   only stateful revisions are served.
+*
+* @example
+* ```ts
+* import { McpHarness } from "@effected/mcp/testing";
+* import { Effect } from "effect";
+*
+* // `ServerLayer` is the server's layer, built without its own `Stdio`.
+* const program = Effect.gen(function* () {
+* 	const harness = yield* McpHarness.make(ServerLayer);
+* 	yield* harness.initialize;
+* 	const tools = yield* harness.listTools;
+* 	return tools.map((tool) => tool.name);
+* }).pipe(Effect.scoped);
+* ```
 *
 * @public
 */
@@ -71,7 +87,7 @@ var McpHarness = class McpHarness {
 	discover;
 	/** Send a request and wait for its response. */
 	request;
-	/** Send a request now; wait for its response later. Fails with `NotInitialized`, sending nothing, on a stateful revision before `initialize`. */
+	/** Send a request now; wait for its response later. Fails with `NotInitialized`, sending nothing, on a stateful revision before `initialize` (`ping` excepted). */
 	startRequest;
 	/** Send a notification. */
 	notify;
@@ -193,7 +209,7 @@ var McpHarness = class McpHarness {
 			return Effect.asVoid(Queue.offer(stdin, encoder.encode(`${line}\n`)));
 		});
 		const startRequest = (method, params) => Effect.gen(function* () {
-			if (stateful && !initializeSent && method !== "initialize") return yield* new McpTestFailure({
+			if (stateful && !initializeSent && method !== "initialize" && method !== "ping") return yield* new McpTestFailure({
 				reason: "NotInitialized",
 				message: `${method} was not sent: call initialize first on stateful protocol ${protocol.protocolVersion}`
 			});

package/McpProbe.js

@@ -3,7 +3,7 @@ import { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMes
 import { McpTestFailure } from "./McpTestFailure.js";
 import { McpProcess } from "./McpProcess.js";
 import { Effect } from "effect";
-import { McpProtocol } from "effect/unstable/ai";
+import { McpProtocol } from "effect/ai";
 
 //#region src/McpProbe.ts
 /**
@@ -12,8 +12,7 @@ import { McpProtocol } from "effect/unstable/ai";
 *
 * @remarks
 * Stdin stays open until the id-1 response has arrived. Closing it right
-* after writing, as every hand-rolled smoke test did, makes an Effect server
-* drop the in-flight response and exit 0, so a slow boot reads as a pass with
+* after writing makes an Effect server drop the in-flight response and exit 0, so a slow boot reads as a pass with
 * no response. The caller asserts `response.error === undefined`, `stderr` is
 * empty and `exitCode` is 0; this is the MCP half of a packed-install proof.
 * Checking stderr and the exit code alone passes a server that answers
@@ -27,6 +26,20 @@ import { McpProtocol } from "effect/unstable/ai";
 * - A child that ignores stdin EOF never exits, and the probe waits for it.
 *   Wrap the probe in `Effect.timeout`.
 *
+* @example
+* ```ts
+* import { McpProbe } from "@effected/mcp/testing";
+* import { Effect } from "effect";
+* import { ChildProcess } from "effect/process";
+*
+* const program = Effect.gen(function* () {
+* 	const probe = yield* McpProbe.initialize(ChildProcess.make(process.execPath, ["./bin/server.js"]));
+* 	// A clean boot: no JSON-RPC error, empty stderr, exit code 0.
+* 	return probe.response.error === undefined && probe.stderr === "" && probe.exitCode === 0;
+* });
+* // Requires a `ChildProcessSpawner` from the platform layer.
+* ```
+*
 * @public
 */
 var McpProbe = class {

package/McpProcess.js

@@ -2,8 +2,8 @@ import { ToolFailure } from "./ToolFailure.js";
 import { DEFAULT_CLIENT_INFO, STDERR_HINT, frame, initializeParams, isJsonRpcMessage, isResponse, isStateless, parseFrame } from "./internal/wire.js";
 import { McpTestFailure } from "./McpTestFailure.js";
 import { Deferred, Effect, Queue, Ref, Stream } from "effect";
-import { McpProtocol } from "effect/unstable/ai";
-import { ChildProcessSpawner } from "effect/unstable/process";
+import { McpProtocol } from "effect/ai";
+import { ChildProcessSpawner } from "effect/process";
 
 //#region src/McpProcess.ts
 /**
@@ -25,6 +25,23 @@ import { ChildProcessSpawner } from "effect/unstable/process";
 * - A request in flight when stdin closes is dropped by an Effect server:
 *   read its response first.
 *
+* @example
+* ```ts
+* import { McpProcess } from "@effected/mcp/testing";
+* import { Effect } from "effect";
+* import { ChildProcess } from "effect/process";
+*
+* const program = Effect.gen(function* () {
+* 	const child = yield* McpProcess.spawn(ChildProcess.make(process.execPath, ["./bin/server.js"]));
+* 	yield* child.handshake();
+* 	yield* child.send({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+* 	const { response } = yield* child.readUntilResponse(2);
+* 	yield* child.closeStdin;
+* 	return response;
+* }).pipe(Effect.scoped);
+* // Requires a `ChildProcessSpawner` from the platform layer.
+* ```
+*
 * @public
 */
 var McpProcess = class McpProcess {

package/McpStdio.js

@@ -1,7 +1,7 @@
 import { LaunchFailed } from "./internal/LaunchFailed.js";
 import { makeGuardedStdio } from "./internal/StdinFrames.js";
 import { Cause, Effect, Exit, Layer, References, Runtime } from "effect";
-import { McpProtocol, McpServer } from "effect/unstable/ai";
+import { McpProtocol, McpServer } from "effect/ai";
 
 //#region src/McpStdio.ts
 /**
@@ -39,10 +39,9 @@ var McpStdio = class McpStdio {
 	* first, then the two newest stateful ones.
 	*
 	* @remarks
-	* Real clients open with either handshake: Claude Code 2.1.281 was
-	* measured opening a stdio server with the stateless `server/discover`,
-	* while most other shipping clients still send `initialize`. The order
-	* is load-bearing:
+	* Real clients open with either handshake: some (Claude Code, for one)
+	* open a stdio server with the stateless `server/discover`, while others
+	* still send `initialize`. The order is load-bearing:
 	*
 	* - Stateless first: a request with no session and no `_meta` falls to
 	*   `protocols[0]`.
@@ -68,26 +67,35 @@ var McpStdio = class McpStdio {
 	*
 	* The server reads stdin through a guard that frames it exactly as core's
 	* decoder does: one streaming UTF-8 decoder, a byte-order mark stripped
-	* only at the start of the stream, lines split on `\n`. A line that is
-	* not JSON is answered on stdout with a JSON-RPC parse error, code
-	* `-32700` and `id: null`, and never reaches core's decoder, which would
-	* otherwise throw on that line again for every later chunk and stop
-	* answering. So is a line longer than core's cap of 16 Mi UTF-16 code
-	* units: it is answered once, as soon as it passes the cap, and the rest
-	* of it is discarded up to its newline. A line of JSON whitespace (space,
-	* tab, carriage return) is ignored.
+	* only at the start of the stream, lines split on `\n`. Core itself skips
+	* a line it cannot use and keeps serving, but sends no reply, where
+	* JSON-RPC 2.0 requires one; the guard supplies it. A line that is not
+	* JSON is answered on stdout with a parse error, code `-32700` and
+	* `id: null`, and never reaches core. So is a line longer than core's cap
+	* of 16 Mi UTF-16 code units: it is answered once, as soon as it passes
+	* the cap, and the rest of it is discarded up to its newline (core would
+	* log it on stderr and drop it). A line of JSON whitespace (space, tab,
+	* carriage return) is ignored.
 	*
 	* A line that is JSON but no JSON-RPC message core can handle is answered
 	* with an Invalid Request, code `-32600` and `id: null`, and never reaches
-	* core: a value that is neither an object nor an array (core throws on
-	* `null`, dropping every other frame in its chunk, and ignores a number,
-	* string or boolean without a reply), an object whose `method` is not a
-	* string and whose `id` is absent or `null` (core throws on it too), and
-	* an object with neither `method` nor `id`, which is neither a request nor
-	* a response. Everything else goes to core: an array, which core answers
-	* `-32600` itself because it serves no batches; an object with an `id`
-	* and no `method`, which is a response and gets no reply; and a request
-	* with an `id`, which core answers even when its `method` is malformed.
+	* core: a value that is neither an object nor an array, an object whose
+	* `method` is not a string and whose `id` is absent or `null`, and an
+	* object with neither `method` nor `id`, which is neither a request nor a
+	* response.
+	*
+	* A line whose `method` starts with `@effect/rpc/` never reaches core,
+	* whose JSON-RPC decoder would read one without an `id` as its own RPC
+	* control message: `@effect/rpc/Eof` alone silently stops the server
+	* (Effect-TS/effect#8499, open upstream). Such a request is answered
+	* `-32601` Method not found, echoing its `id`; such a notification is
+	* dropped. The guard stops doing this once core no longer treats a
+	* client's `@effect/rpc/` frame as a control message.
+	*
+	* Everything else goes to core: an array, which core answers `-32600`
+	* itself because it serves no batches; an object with an `id` and no
+	* `method`, which is a response and gets no reply; and a request with an
+	* `id`, which core answers even when its `method` is malformed.
 	*
 	* Give each server a fresh layer memo map. Core's stdio protocol layer
 	* is a shared constant, so a second `McpStdio.layer` server whose build

package/McpTestFailure.js

@@ -18,8 +18,8 @@ import { Schema } from "effect";
 *   not `catchTag`.
 * - `ServerStopped` (`McpHarness`): the in-process server stopped, usually
 *   because stdin closed while the request was in flight.
-* - `NotInitialized` (`McpHarness`): a request other than `initialize` was
-*   made on a stateful revision before `initialize` was sent. The request
+* - `NotInitialized` (`McpHarness`): a request other than `initialize` or
+*   `ping` was made on a stateful revision before `initialize` was sent. The request
 *   is never written; the server would only have refused it opaquely:
 *   `-32602 Invalid request metadata` when a stateless adapter is listed
 *   first, `-32603 Internal error` when only stateful revisions are served.
@@ -30,6 +30,7 @@ import { Schema } from "effect";
 * @public
 */
 var McpTestFailure = class extends Schema.TaggedError()("McpTestFailure", {
+	/** Which failure occurred; see the list above for which client raises which. */
 	reason: Schema.Literals([
 		"StreamEnded",
 		"ServerStopped",
@@ -37,6 +38,7 @@ var McpTestFailure = class extends Schema.TaggedError()("McpTestFailure", {
 		"NotInitialized",
 		"ErrorResponse"
 	]),
+	/** A human-readable description of what went wrong. */
 	message: Schema.String
 }) {};
 

package/McpToolAudit.js

@@ -24,10 +24,12 @@ const objectNodes = (schema) => {
 			return acc;
 		}, Object.create(null));
 		const closed = merged.some((part) => part.additionalProperties === false);
+		const droppedKeyCheck = merged.some((part) => isNode(part.additionalProperties) && isNode(part.propertyNames));
 		if (isNode(properties) || merged.some((part) => part.type === "object")) out.push({
 			path,
 			properties,
-			closed
+			closed,
+			droppedKeyCheck
 		});
 		if (isNode(properties)) for (const [key, child] of Object.entries(properties)) visit(child, join(path, key));
 		visit(node.items, join(path, "items"));
@@ -81,9 +83,9 @@ var McpToolAudit = class {
 			};
 			if (seen.has(tool.name)) report("duplicate tool name");
 			seen.add(tool.name);
-			if (policy.input !== "any") for (const { path, properties, closed } of objectNodes(tool.inputSchema)) {
+			if (policy.input !== "any") for (const { path, properties, closed, droppedKeyCheck } of objectNodes(tool.inputSchema)) {
 				const where = path === "" ? "the root" : path;
-				if (policy.input === "closed" && !closed) report(`input schema is open at ${where}`);
+				if (policy.input === "closed" && !closed) report(`input schema is open at ${where}${droppedKeyCheck ? " (a Record whose key check was not served; a key pattern is served closed, as patternProperties, only when its RegExp has the u flag, e.g. Schema.isPattern(/^x-/u))" : ""}`);
 				if (policy.input === "open" && isNode(properties) && closed) report(`input schema is closed at ${where}`);
 			}
 			const title = tool.title ?? tool.annotations?.title;

package/McpToolkit.js

@@ -1,6 +1,7 @@
+import { ToolFailure } from "./ToolFailure.js";
 import { ToolInputSchema } from "./ToolInputSchema.js";
 import { Context, Effect, Layer, Schema } from "effect";
-import { McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
+import { McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
 
 //#region src/McpToolkit.ts
 /** The union a {@link McpToolkit.unionTool} decodes with; read by the `McpToolkit.layer` decorator. */
@@ -17,79 +18,120 @@ const unionInputJsonSchema = (parameters) => {
 	});
 };
 const invalidParameters = (name, message) => new McpSchema.InvalidParams({ message: `Invalid parameters for tool '${name}': ${message}` });
-/** The rendering both union paths use when the caller names none: `ToolInputSchema.formatUnknownKeys`. */
-const defaultUnknownKeyMessage = (levels) => ToolInputSchema.formatUnknownKeys(levels);
+const MAX_ACCEPTED_LINES = 20;
+/**
+* `path` as core renders an issue path, `["a"][0]["b"]`: a segment indexing
+* an array in `payload` is bare, any other is a JSON string. Truncated, since
+* the segments are the caller's keys.
+*/
+const issuePath = (payload, path) => {
+	let node = payload;
+	let out = "";
+	for (const segment of path) {
+		out += Array.isArray(node) ? `[${segment}]` : `[${JSON.stringify(segment)}]`;
+		node = typeof node === "object" && node !== null ? node[segment] : void 0;
+	}
+	return ToolFailure.truncate(out);
+};
+/**
+* One line per level of `payload` that carries a key the served
+* `inputSchema` does not accept: `Accepted params at <path>: a, b.`, with
+* `keys matching <pattern>` for a level that also accepts keys by
+* `patternProperties`, and `This tool accepts no params.` for a
+* zero-parameter root. At most 20 lines; empty when no level has an
+* unknown key.
+*/
+const acceptedParamsLines = (payload, inputSchema) => ToolInputSchema.unknownKeys(payload, inputSchema).slice(0, MAX_ACCEPTED_LINES).map((level) => {
+	const patterns = level.acceptedPatterns ?? [];
+	if (level.path.length === 0 && level.accepted.length === 0 && patterns.length === 0) return "This tool accepts no params.";
+	const parts = [...level.accepted.length > 0 ? [level.accepted.join(", ")] : [], ...patterns.length > 0 ? [`keys matching ${patterns.join(", ")}`] : []];
+	return `Accepted params at ${level.path.length === 0 ? "the root" : issuePath(payload, level.path)}: ${parts.length > 0 ? parts.join("; ") : "(none)"}.`;
+});
+/**
+* `error` with {@link acceptedParamsLines} appended to its message, one per
+* line after core's own report; `error` itself when there is nothing to add.
+* Core stays the decoder: this only annotates the report it produced.
+*/
+const withAcceptedParams = (error, payload, inputSchema) => {
+	const lines = acceptedParamsLines(payload, inputSchema);
+	return lines.length === 0 ? error : new McpSchema.InvalidParams({
+		message: [error.message, ...lines].join("\n"),
+		...error.data !== void 0 ? { data: error.data } : {}
+	});
+};
 /**
 * The one decode a union tool's payload gets, shared by the `McpToolkit.layer`
-* decorator and {@link McpToolkit.unionHandler}: every unknown key at every
-* depth named in one `InvalidParams` (walked over the served `inputSchema`),
-* then the union's strict decode, whose failure is worded as core words a
-* `Tool.make` one. Suspended, so a throwing `format` dies inside the call.
+* decorator and {@link McpToolkit.unionHandler}: the union's strict decode
+* with the options core decodes a strict `Tool.make` tool with
+* (`onExcessProperty: "error"`, `errors: "all"`), so every excess, missing and
+* invalid field of the matched member is reported together, worded as core
+* words a `Tool.make` failure, with the accepted params appended as the layer
+* appends them to core's own report.
 */
-const decodeUnionPayload = (name, union, inputSchema, format) => {
+const decodeUnionPayload = (name, union, inputSchema) => {
 	const decode = Schema.decodeUnknownEffect(union);
-	return (payload) => Effect.suspend(() => {
+	return (payload) => {
 		const raw = payload ?? {};
-		const levels = ToolInputSchema.unknownKeys(raw, inputSchema);
-		if (levels.length > 0) return Effect.fail(new McpSchema.InvalidParams({ message: format(levels) }));
-		return decode(raw, { onExcessProperty: "error" }).pipe(Effect.mapError((error) => invalidParameters(name, error.message)));
-	});
+		return decode(raw, {
+			onExcessProperty: "error",
+			errors: "all"
+		}).pipe(Effect.mapError((error) => withAcceptedParams(invalidParameters(name, error.message), raw, inputSchema)));
+	};
 };
 /**
 * The registration `McpToolkit.layer` hands core in place of `registration`:
-* a union tool gets its payload decoded first, a strict tool its unknown keys
-* refused first, and anything else passes through untouched. The wrapped
-* handler is built only after the check passes, so a rejected payload never
-* reaches it.
+* a union tool gets its payload decoded first, with the wrapped handler built
+* only after the decode passes, so a rejected payload never reaches it.
+* Anything else is decoded by core as before, and core's parameter failure,
+* the only `InvalidParams` its `handle` fails with, gets the accepted params
+* appended.
 *
 * @internal
 */
-const guardRegistration = (registration, format) => {
+const guardRegistration = (registration) => {
 	const union = Context.get(registration.annotations, UnionParameters);
-	if (union !== void 0) {
-		const check = decodeUnionPayload(registration.tool.name, union, registration.tool.inputSchema, format);
-		return {
-			...registration,
-			handle: (payload) => check(payload).pipe(Effect.flatMap(() => registration.handle(payload)))
-		};
-	}
-	return Context.get(registration.annotations, Tool.Strict) === true ? {
+	if (union === void 0) return {
 		...registration,
-		handle: (payload) => Effect.suspend(() => {
-			const levels = ToolInputSchema.unknownKeys(payload ?? {}, registration.tool.inputSchema);
-			return levels.length > 0 ? Effect.fail(new McpSchema.InvalidParams({ message: format(levels) })) : registration.handle(payload);
-		})
-	} : registration;
+		handle: (payload) => registration.handle(payload).pipe(Effect.catchTag("InvalidParams", (error) => Effect.fail(withAcceptedParams(error, payload ?? {}, registration.tool.inputSchema))))
+	};
+	const check = decodeUnionPayload(registration.tool.name, union, registration.tool.inputSchema);
+	return {
+		...registration,
+		handle: (payload) => check(payload).pipe(Effect.flatMap(() => registration.handle(payload)))
+	};
 };
 const DEFAULT_STRICT = "all";
 const strictened = (toolkit, mode) => mode === "annotated" ? toolkit : Toolkit.make(...Object.values(toolkit.tools).map((tool) => Tool.isDynamic(tool) || Tool.getStrictMode(tool) !== void 0 ? tool : tool.annotate(Tool.Strict, true)));
 /**
-* Register a toolkit exactly as core's `McpServer.toolkit` does, except that a
-* strict tool's unknown arguments are all named, at every depth, in one
-* response.
+* Register a toolkit exactly as core's `McpServer.toolkit` does, except that
+* every tool is strict by default and a {@link McpToolkit.unionTool} gets its
+* union decoded.
 *
 * @remarks
-* Rejection itself is core's: a tool annotated `Tool.Strict` is served with
-* `additionalProperties: false` on every object node and decoded with
-* `onExcessProperty: "error"`. But core reports only the FIRST excess key
-* (`Expected no excess property at ["extra"]`), so an agent fixes one typo
-* per round trip and never learns about a nested one until the next call.
-* This layer is the better report, not the rejecter: it runs core's
+* Rejection and reporting are core's: a tool annotated `Tool.Strict` is
+* served with `additionalProperties: false` on every object node and decoded
+* with `onExcessProperty: "error"` and `errors: "all"`, so one
+* `InvalidParams` names every excess key at every depth together with every
+* missing or invalid field. The layer appends to that report, never in place
+* of it: for every object level of the payload that carries a key the served
+* input schema does not accept, one line naming what that level does accept,
+* `Accepted params at the root: query, filter.` or
+* `Accepted params at ["filter"]: kind, tag.` (the path as core writes it),
+* with `keys matching <pattern>` for keys a `patternProperties` level
+* accepts, and `This tool accepts no params.` for a zero-parameter tool. An
+* agent can fix the call from the reply alone. A failure with no unknown key
+* (a missing or mistyped field only) is core's report unchanged. The lines
+* are appended to core's `InvalidParams` as it leaves the tool's registered
+* handler, the one failure that handler has for bad parameters.
+*
+* On top of that is the policy: under
+* `strict: "all"` (the default) it annotates every tool that carries no
+* `Tool.Strict` annotation of its own as strict, skipping `Tool.dynamic`
+* tools (core dies at registration on a strict dynamic tool). It runs core's
 * `registerToolkit` unchanged under a registration-scoped `McpServer` whose
-* `addTool` puts a `ToolInputSchema.unknownKeys` pre-check in front of each
-* handler. The pre-check walks the input schema the tool actually serves
-* (after core's own top-level `$ref` inlining), follows `$ref`, `allOf` and
-* discriminated `oneOf`/`anyOf` members, and fails with one
-* `McpSchema.InvalidParams` naming every unknown key path plus the accepted
-* params, before core decodes. Core's strict decode stays behind it as the
-* backstop. The pre-check is gated on the same predicate core uses to choose
-* strict decoding — the registered tool's `Tool.Strict` annotation is
-* `true` — so a lenient tool (explicit `Tool.Strict` false, a
-* `Tool.dynamic` tool, or any unannotated tool under `"annotated"`) is
-* never rejected here, even when its raw JSON Schema carries
-* `additionalProperties: false`. The pre-check runs under `Effect.suspend`,
-* so a throwing `unknownKeyMessage` dies inside the call's effect. No core
-* internals are patched, so this survives an rc bump without re-diffing.
+* `addTool` puts the union decode in front of a union tool's handler and
+* passes every other registration through untouched. It patches no core
+* internals: it uses only `McpServer.registerToolkit` and `addTool`.
 *
 * Registration goes through core's module-level `McpServer.McpServer.layer`,
 * shared by reference with `McpStdio.layer`'s own copy — provide both into
@@ -128,9 +170,11 @@ var McpToolkit = class {
 	* {@link McpToolkit.unionHandler}, which receives the decoded member.
 	*
 	* Registered through {@link McpToolkit.layer}, a union tool gets the same
-	* treatment as a strict `Tool.make` tool: every unknown key named in one
-	* `InvalidParams`, then a strict decode, both before the handler runs, so
-	* bad arguments answer JSON-RPC `-32602` on `2025-06-18` and an `isError`
+	* treatment as a strict `Tool.make` tool: a strict decode with
+	* `errors: "all"` before the handler runs, reporting every excess, missing
+	* and invalid field of the matched member in one `InvalidParams`, with the
+	* same `Accepted params at <path>: …` lines appended, so bad
+	* arguments answer JSON-RPC `-32602` on `2025-06-18` and an `isError`
 	* result on the later revisions, exactly as a `Tool.make` decode failure
 	* does. Registered through core's `McpServer.toolkit` it still decodes
 	* strictly, in the handler, but the `InvalidParams` is then a declared
@@ -141,6 +185,11 @@ var McpToolkit = class {
 	*
 	* @example
 	* ```ts
+	* import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
+	* import { Schema } from "effect";
+	* import { Tool } from "effect/ai";
+	*
+	* // `AddNote`, `ListNotes`, `Added`, `Listed` are object schemas; `Kit` is a Toolkit that includes `Note`.
 	* const Note = McpToolkit.unionTool("note", {
 	*   parameters: Schema.Union([AddNote, ListNotes]),
 	*   success: ToolOutputSchema.objectRooted(Schema.Union([Added, Listed])),
@@ -159,36 +208,36 @@ var McpToolkit = class {
 		return Object.assign(tool, { unionParameters: options.parameters });
 	};
 	/**
-	* The handler for a {@link McpToolkit.unionTool}: checks and decodes the
-	* raw payload exactly as {@link McpToolkit.layer} does, and passes the
-	* decoded member to `handler`.
+	* The handler for a {@link McpToolkit.unionTool}: decodes the raw payload
+	* exactly as {@link McpToolkit.layer} does, and passes the decoded member
+	* to `handler`.
 	*
 	* @remarks
-	* A payload carrying unknown keys fails with one `McpSchema.InvalidParams`
-	* naming every one of them, at every depth, in the
-	* `ToolInputSchema.formatUnknownKeys` report (or `options.unknownKeyMessage`'s),
-	* walked over the tool's served input schema. A payload that then does
-	* not decode fails `InvalidParams` worded as core words a `Tool.make`
-	* decode failure. It is the same implementation the layer runs, so a
-	* handler called directly (a test helper, or a toolkit registered through
-	* core's `McpServer.toolkit`) reports what a client of the layer sees.
-	* Under {@link McpToolkit.layer} the layer has already rejected a bad
-	* call before the handler runs, and its own `unknownKeyMessage` wins.
+	* A payload that does not decode strictly fails with one
+	* `McpSchema.InvalidParams`, worded as core words a `Tool.make` decode
+	* failure, naming every excess key at every depth together with every
+	* missing or invalid field of the matched member, then one
+	* `Accepted params at <path>: …` line per level with an unknown key. It
+	* is the same
+	* implementation the layer runs, so a handler called directly (a test
+	* helper, or a toolkit registered through core's `McpServer.toolkit`)
+	* reports what a client of the layer sees. Under {@link McpToolkit.layer}
+	* the layer has already rejected a bad call before the handler runs.
+	* `options.unknownKeyMessage` is deprecated and ignored.
 	*/
-	static unionHandler = (tool, handler, options = {}) => {
-		const check = decodeUnionPayload(tool.name, tool.unionParameters, tool.jsonSchema, options.unknownKeyMessage ?? defaultUnknownKeyMessage);
+	static unionHandler = (tool, handler, _options = {}) => {
+		const check = decodeUnionPayload(tool.name, tool.unionParameters, tool.jsonSchema);
 		return (payload) => check(payload).pipe(Effect.flatMap(handler));
 	};
 	/**
-	* `McpServer.toolkit`'s registration layer, strict by default and naming
-	* every unknown argument in one `InvalidParams`.
+	* `McpServer.toolkit`'s registration layer, strict by default.
+	* `options.unknownKeyMessage` is deprecated and ignored.
 	*/
 	static layer = (toolkit, options = {}) => Layer.effectDiscard(Effect.gen(function* () {
 		const registry = yield* McpServer.McpServer;
-		const format = options.unknownKeyMessage ?? defaultUnknownKeyMessage;
 		const decorated = McpServer.McpServer.of({
 			...registry,
-			addTool: (registration) => registry.addTool(guardRegistration(registration, format))
+			addTool: (registration) => registry.addTool(guardRegistration(registration))
 		});
 		yield* McpServer.registerToolkit(strictened(toolkit, options.strict ?? DEFAULT_STRICT)).pipe(Effect.provideService(McpServer.McpServer, decorated));
 	})).pipe(Layer.provide(McpServer.McpServer.layer));