Add `outputSchema` to `ModelContextTool` and `RegisteredTool` by beaufortfrancois · Pull Request #254 · webmachinelearning/webmcp

beaufortfrancois · 2026-08-21T13:27:47Z

This PR adds an optional outputSchema member to the ModelContextTool and RegisteredTool dictionaries to enable browser agents and in-page agents to help LLMs reliably reason about the return values of tools.

While responseConstraint was previously discussed, that name is too specific to the Built-in AI / Prompt API. TheoutputSchema name aligns directly with the MCP Tools specification outputSchema used to define expected structured outputs with JSON Schema.

FIX #9

Preview | Diff

Codify WebMCP JSON Schema subset (Draft 2020-12) per 2026-03-05 CG resolution. Meta-validation in registerTool() (TypeError on invalid schema) and input validation in executeTool() parallel block before tool execute steps (DataError with {path,reason,schemaPath} for agent self-correction). Spec-only per review; WPT split to web-platform-tests/wpt (tentative). Coordinates with webmachinelearning#254 (outputSchema, same dictionaries).

volkandkaya · 2026-09-08T04:32:09Z

Is this still planned on being added?

beaufortfrancois · 2026-09-11T11:15:34Z

Is this still planned on being added?

I hope so :) 🤞

@domfarolino I've started experimenting with outputSchema in Chromium with https://chromium-review.googlesource.com/c/chromium/src/+/8398367 to test it out.

markafoltz

A few questions/comments about how the serialization result is passed around (might be missing some key idea)

…utSchema

markafoltz

Looks good % a few optional suggested edits

kenchris · 2026-10-20T17:12:19Z

Thanks for working on this. One thing I'd like to see said explicitly is that leaving out outputSchema is the normal case. A lot of tools return text, and for those, plain text is often the better result: It is cheaper for the model than structured JSON, and a schema would only wrap the text in an object like { "text": "..." } for no benefit. MCP works like that too, where text content is the default and outputSchema with structured output is an addition for tools that want it. The text in the PR says output is expected to conform to the schema, which is fine when there is one, but a sentence saying that tools without one are not expected to return structured data would make that clear.

Related, and a question more than a request: since results are serialized as JSON, a tool that returns a string comes back as a JSON string with quotes and escaped newlines. Is that the intended shape for text results, or is a plain text result something to look at separately (maybe together with the typed results work in #41 and #282)?

On sjdallst2's question about validation, I'd say a result that doesn't match should reach the host as a tool error, so the host can tell it from a normal result and decide what to do. Also, a schema is written by the page, so the description fields inside it are model-visible text from the page and should get the same treatment as tool descriptions.

beaufortfrancois · 2026-10-26T15:03:04Z

@kenchris We're discussing whether outputSchema should be optional or not in #92

beaufortfrancois · 2026-10-26T15:03:18Z

@domfarolino I think we're good now.

SHA: 6cd745a Reason: push, by domfarolino Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

This adds an optional outputSchema dictionary member to ModelContextTool and RegisteredTool to define the expected structure of tool execution return values. Upon registration, outputSchema is serialized with the tool schema serialization algorithm, throwing a TypeError on serialization failure before checking abort signals. getTools() exposes outputSchema as a parsed JSON Schema object, or undefined when omitted. Spec PR: webmachinelearning/webmcp#254 Bug: 489045948 Bug: 565876481 Change-Id: I5e333c74c834cd6bc29253609e4e3d74edb09d08

This adds an optional outputSchema dictionary member to ModelContextTool and RegisteredTool to define the expected structure of tool execution return values. Upon registration, outputSchema is serialized with the tool schema serialization algorithm, throwing a TypeError on serialization failure before checking abort signals. getTools() exposes outputSchema as a parsed JSON Schema object, or undefined when omitted. Spec PR: webmachinelearning/webmcp#254 Bug: 489045948 Bug: 565876481 Change-Id: I5e333c74c834cd6bc29253609e4e3d74edb09d08 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/8398367 Reviewed-by: Khushal Sagar <khushalsagar@chromium.org> Reviewed-by: Dominic Farolino <dom@chromium.org> Commit-Queue: Fr <beaufort.francois@gmail.com> Cr-Commit-Position: refs/heads/main@{#1732837}

Follows webmachinelearning/webmcp#254, which adds an optional outputSchema to ModelContextTool and RegisteredTool. The content script forwards RegisteredTool.outputSchema to the side panel, which sends it as its own field of each tool declaration. Only Gemini gives it to the model, as responseJsonSchema on the function declaration. The AI SDK's Google provider only sends name, description and parametersJsonSchema, and the SDK's own tool outputSchema never reaches any provider, so the Google provider's fetch adds the field to the request body. The model is opened for each turn with that turn's output schemas, so concurrent chats never see each other's tools. OpenAI, Anthropic, Ollama and the on-device Prompt API have no such field, and the schema is not mixed into the tool description either. webmcp-types does not declare outputSchema yet, so the WebMCP types are augmented locally until it does.

Follows webmachinelearning/webmcp#254, which adds an optional outputSchema to ModelContextTool and RegisteredTool. The content script forwards RegisteredTool.outputSchema to the side panel, which checks every result of that tool against it, before the result is truncated or spotlighted. A result that does not match goes back to the model as a tool error saying where it differs, as MCP clients do with structured content. A schema that cannot be used is the page's mistake, so the result is then passed on unchecked. The check is done in the side panel, so it holds for the backend server and the on-device Prompt API alike. The schema is not sent to any model: only Gemini has a field for it, and the model is better served by results known to match than by a description of what they should look like. Results are validated with @cfworker/json-schema, which never evaluates code, as the extension's content security policy requires. webmcp-types does not declare outputSchema yet (webmachinelearning/webmcp-types#16), so RegisteredTool is augmented locally until it does.

The spec added outputSchema to ModelContextTool and RegisteredTool (webmachinelearning/webmcp#254, merged 2026-11-02; Chrome 159): a JSON Schema for the tool's result, which agents may use to reject a result that does not validate. It is reactive and compared by content like inputSchema, so a change re-registers the tool and a rebuilt identical object does not. useWebMCPTools and defineWebMCPTool take it through the shared options type, the stub stores it and returns it from getTools(), and the descriptor and RegisteredTool types declare it until webmcp-types does (its PR #16 is open). Normalization is unchanged, as in use-webmcp-tool's open PR #18: the spec defines no structured result field, and a { content } value already passes through untouched for tools that want to add structuredContent.

beaufortfrancois requested a review from domfarolino August 21, 2026 13:27

davewo83 mentioned this pull request Aug 27, 2026

Implementer note: same-core decision tool + Inspector NL→enum mapping #263

Closed

arnabwithab mentioned this pull request Sep 3, 2026

Input validation (Fixes #92) #289

Closed

7 tasks done

obetomuniz mentioned this pull request Sep 11, 2026

feat(webmcp): support native outputSchema in trial browsers obetomuniz/web-ai-sdk#177

Open

7 tasks

beaufortfrancois force-pushed the outputSchema branch from a7e008f to a988ee0 Compare September 11, 2026 09:59

Add outputSchema to ModelContextTool and RegisteredTool

ec56f58

beaufortfrancois force-pushed the outputSchema branch from a988ee0 to ec56f58 Compare October 1, 2026 08:49

markafoltz self-requested a review October 8, 2026 22:48

markafoltz reviewed Oct 8, 2026

View reviewed changes

Comment thread index.bs Resolved

Comment thread index.bs Resolved

Comment thread index.bs Resolved

Comment thread index.bs Resolved

Comment thread index.bs Resolved

Comment thread index.bs Resolved

beaufortfrancois added 2 commits October 9, 2026 09:14

Merge branch 'main' of github.com:webmachinelearning/webmcp into outp…

bf42aa7

…utSchema

Address review feedback on outputSchema

ea1d089

markafoltz approved these changes Oct 9, 2026

View reviewed changes

Comment thread index.bs Resolved

Comment thread index.bs Resolved

Comment thread index.bs Resolved

Comment thread index.bs Resolved

Comment thread README.md Resolved

beaufortfrancois added 4 commits October 12, 2026 13:19

Fix note markup in serialize a tool schema

bbfa0b0

Clarify circular reference example in serialize a tool schema note

2ab2c3d

Make serialize a tool schema exception reference explicit

6e21548

Rename Parameters schema to Input schema in README example

b79a5df

anssiko mentioned this pull request Oct 12, 2026

WebML WG/CG F2F Agenda - TPAC 2026 (Dublin, Ireland) webmachinelearning/meetings#39

Closed

markafoltz approved these changes Oct 12, 2026

View reviewed changes

beaufortfrancois mentioned this pull request Oct 13, 2026

feat(webmcp): expose tool outputSchema puppeteer/puppeteer#15579

Open

sjdallst2 reviewed Oct 14, 2026

View reviewed changes

Comment thread index.bs Resolved

chromium-wpt-export-bot mentioned this pull request Oct 16, 2026

[WebMCP] Add outputSchema to ModelContextTool and RegisteredTool web-platform-tests/wpt#63800

Merged

domfarolino mentioned this pull request Oct 20, 2026

Introduce the Tool interface #348

Open

domfarolino approved these changes Oct 20, 2026

View reviewed changes

Comment thread index.bs Resolved

kurotanshi mentioned this pull request Oct 26, 2026

本週技術趨勢週報（2026-W44） kurotanshi/grok-weekly#7

Open

Clarify when tool schemas are the empty string

cc2ec99

dkdndes mentioned this pull request Nov 1, 2026

docs(readme): public links, preview status and outputSchema extension for PyPI alpininsight/ais-webmcp#33

Merged

domfarolino approved these changes Nov 2, 2026

View reviewed changes

domfarolino merged commit 6cd745a into webmachinelearning:main Nov 2, 2026
2 checks passed

github-actions Bot added a commit that referenced this pull request Nov 2, 2026

Add outputSchema to ModelContextTool and RegisteredTool (#254)

fd31615

SHA: 6cd745a Reason: push, by domfarolino Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

beaufortfrancois deleted the outputSchema branch November 2, 2026 13:12

dkdndes mentioned this pull request Nov 2, 2026

docs: npm release pending; outputSchema in WebMCP draft spec (#254) alpininsight/ais-webmcp#42

Merged

This was referenced Nov 3, 2026

Add outputSchema support GoogleChromeLabs/use-webmcp-tool#18

Open

Add support for tool outputSchema GoogleChromeLabs/webmcp-extension#98

Open

andreban mentioned this pull request Nov 4, 2026

[webmcp-skills] Add outputSchema support and best practices to build-webmcp-tools GoogleChromeLabs/webmcp-tools#618

Open

5 tasks

beaufortfrancois mentioned this pull request Nov 4, 2026

feat: add outputSchema and infer execute output from it webmachinelearning/webmcp-types#16

Open

andreban mentioned this pull request Nov 4, 2026

feat(skills): add outputSchema support and best practices to build-webmcp-tools GoogleChromeLabs/webmcp-tools#619

Open

MrSunshyne mentioned this pull request Nov 7, 2026

Add an outputSchema option MrSunshyne/vue-webmcp#44

Open

ikram1201 mentioned this pull request Nov 7, 2026

Who owns the validation layer? #92

Open

kurotanshi mentioned this pull request Nov 9, 2026

本週技術趨勢週報（2026-W46） kurotanshi/grok-weekly#9

Open

Conversation

beaufortfrancois commented Aug 21, 2026 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

volkandkaya commented Sep 8, 2026

Uh oh!

beaufortfrancois commented Sep 11, 2026

Uh oh!

markafoltz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

markafoltz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kenchris commented Oct 20, 2026

Uh oh!

Uh oh!

beaufortfrancois commented Oct 26, 2026

Uh oh!

beaufortfrancois commented Oct 26, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

beaufortfrancois commented Aug 21, 2026 •

edited by pr-preview Bot

Loading