Clarify executeTool argument encoding and returned schema shape

[zekariasasaminew]

While testing WebMCP tool registration and invocation in a browser implementation, I hit two API details that were easy to misread from the current examples/spec text.

Observed behavior:

const tools = await document.modelContext.getTools();
const tool = tools.find((entry) => entry.name === "example_tool");

await document.modelContext.executeTool(tool, { message: "hello" });
// Fails with an input parsing / type error in the tested runtime.

await document.modelContext.executeTool(tool, JSON.stringify({ message: "hello" }));
// Succeeds in the tested runtime.

console.log(typeof tool.inputSchema);
// "string" in the tested runtime, containing serialized JSON schema.

The shape that worked was:

1. Await document.modelContext.getTools().
2. Pass the RegisteredTool object returned by getTools() into executeTool(), not the tool name.
3. Pass JSON-encoded argument text into executeTool().
4. Parse returned inputSchema metadata when it is exposed as a serialized JSON string.

It would help implementers if the explainer/spec/docs explicitly state whether executeTool arguments are intended to be a JavaScript object, a JSON string, or implementation-dependent for now, and whether returned tool schemas are expected to be structured objects or serialized strings.

If the current observed behavior is the intended contract, a small normative example for executeTool would prevent a class of false-negative debugging sessions where tools are registered correctly but every manual execution attempt appears broken.

[minjikim89]

A data point from implementing against Chrome 152 (chrome://flags/#enable-webmcp-testing), in case it helps scope the clarification.

#246 changed executeTool() to take an object (merged 2026-08-17). Chrome 152 still requires a JSON string; passing an object fails with:

UnknownError: Failed to parse input arguments

So code written against the current spec text fails against the current Chrome, and the error does not point at the encoding: it reads as a transient fault, which sent us looking in the wrong place for a while. JSON.stringify on the input is the workaround until Chrome catches up.

If the clarification lands, two things would have saved us the detour: saying explicitly which encoding a conforming implementation must accept, and saying whether accepting both is permitted during the transition.

Notes from the build: https://github.com/minjikim89/redline/blob/main/docs/findings.md

[zekariasasaminew]

Thanks for confirming the same behavior in Chrome 152 and for including the exact error.

I checked the current draft and #246 after opening this. The normative contract is now unambiguous in the spec machinery, even if it was easy to miss in the surrounding prose:

• RegisteredTool.inputSchema is a parsed JavaScript object.
• executeTool() takes the RegisteredTool plus a JavaScript object.
• The result of executeTool() remains a JSON string (Promise<DOMString>).

So Chrome 152 requiring a string input and exposing a string schema is implementation lag relative to the current draft, not an implementation-dependent choice. #279 adds the focused prose and discovery/execution example that this issue asked for.

For current Chrome testing, JSON.stringify(input) and parsing a string-valued schema are still necessary compatibility measures. I agree with the conclusion reached in #287 that the standard should not bless both shapes as permanent contracts; that would turn a temporary origin-trial mismatch into lasting ambiguity. The compatibility shim belongs in downstream test tooling until Chrome catches up.

The remaining useful follow-up is implementation tracking: if someone has the Chromium bug/CL for the object-input and parsed-schema update, linking it here would make the transition status visible. Otherwise I think #279 correctly resolves the documentation part of this issue, while the Chrome conformance gap should be tracked separately against Chromium.

[minjikim89]

Thanks for checking the draft text against #246. Here is the implementation tracking you asked for.

Both halves sit under crbug 489045948, "Align implementation with WebMCP spec". As of today:

• Object input (executeTool(tool, object)): CL 8250826, still open. Uploaded 2026-08-17, last updated 2026-09-04. Not landed, which is why Chrome 152 needs JSON.stringify.
• Parsed inputSchema: CL 8248081 landed 2026-08-21, and was reverted the same day by CL 8276309.

The revert is the interesting part, since it was not a spec disagreement. A packaging failure in the "WebMCP - Model Context Tool Inspector" extension was blocking Canary users from using WebMCP tools, so the change was rolled back to unblock them. The commit message says it will be relanded once the extension update ships.

So the schema half is written and reviewed, not pending. A reland is the expected path.

One practical note for test tooling: it may be safer to key a compatibility shim on the observed shape (typeof inputSchema === "string") than on a Chrome version, since the reland could reach Canary users without any signal.

[beaufortfrancois]

I plan to reland this CL this week. Apologies for any inconvenience this caused.