---
title: "navigator.modelContext: Add WebMCP Tools to Your Site"
description: "Add WebMCP tools with registerTool or form attributes. Covers navigator.modelContext vs document.modelContext, annotations, safety and draft status."
url: https://seenlens.com/fixes/add-webmcp-tools
last_updated: 2026-11-06
---

# navigator.modelContext: how to add WebMCP tools to your site

WebMCP lets a web page give browser agents a list of tools they can call, instead of making them click through the interface. It is an early draft, so the check is optional. Use it if your site has search, booking or lead forms. SeenLens reads three signals: tools or annotated forms, the entry point name and form annotations.

By SeenLens. Last updated: 2026-11-06

## What is the status of WebMCP?

WebMCP is a Draft Community Group Report of the Web Machine Learning Community Group, dated 2026-11-02. It is not a W3C Standard and is not on the Standards Track. The editors work at Microsoft and Google. Chrome documents an origin trial that starts in Chrome 149, and a flag, `chrome://flags/#enable-webmcp-testing`, for local development. Chrome's documentation says the proposal is under active discussion and subject to change.

No study shows that agents use WebMCP tools on live sites at scale. Keep the work small.

| Check | Pass | Info or warn | Not applicable |
| --- | --- | --- | --- |
| WebMCP tools | A registerTool call or an annotated form is found | Info when neither is found | The page has no forms and no registerTool call |
| Entry point | The code uses document.modelContext | Warn when it uses only navigator.modelContext | No modelContext use found |
| Form annotations | Every form has toolname or tooldescription | Info when some forms lack both | The page has no forms, or only forms that post to another site |

SeenLens does this with a static scan of the HTML and up to eight same origin scripts. It counts `registerTool(` call sites, not tools, and it cannot see tools that a script registers only after login or after an event. A loop that registers many tools counts as one call site.

## WebMCP tools: tools or annotated forms

The imperative API registers a tool in JavaScript. The Chrome documentation shows this pattern, with `name`, `description`, `inputSchema` and an `execute` callback that returns a result. Bind `execute` to the same function your interface uses, so the tool and the buttons do the same thing.

```text
const mc = document.modelContext ?? navigator.modelContext;

if (mc) {
  const controller = new AbortController();
  mc.registerTool(
    {
      name: "search_help_center",
      description: "Search the help center and return the top article titles.",
      inputSchema: {
        type: "object",
        properties: { query: { type: "string", description: "Search words" } },
        required: ["query"],
      },
      annotations: { readOnlyHint: true },
      execute: async ({ query }) => {
        const results = await searchHelpCenter(query);
        return results.map((r) => r.title).join("\n");
      },
    },
    { signal: controller.signal } // controller.abort() unregisters the tool
  );
}
```

The Chrome documentation lists the annotations `readOnlyHint`, `untrustedContentHint`, `consequentialHint` and `debugging`, available from Chrome 156. Use names that state the action, such as `submit_application`.

In Next.js, run the code in a Client Component with `useEffect`, and call `controller.abort()` in the cleanup function.

Safety matters. Tool metadata and tool output can carry prompt injection. Set `consequentialHint: true` on tools with lasting effects, such as purchases, and `untrustedContentHint` on tools that return user generated text. Chrome advises a confirmation step for sensitive actions.

## WebMCP entry point: document.modelContext or navigator.modelContext

Early WebMCP examples used `navigator.modelContext`. The current draft puts the interface on the document: `document.modelContext`. Chrome's imperative API page also uses `document.modelContext`. SeenLens warns when your code mentions `navigator.modelContext` and never `document.modelContext`.

The fix is the feature detection in the code above: `const mc = document.modelContext ?? navigator.modelContext`. This works in browsers that follow either version. Check the draft before you ship, because the names can change again.

## WebMCP form annotations: toolname and tooldescription

The declarative API turns an HTML form into a tool with attributes. The Chrome documentation lists `toolname`, `tooldescription`, `toolautosubmit` and `toolparamdescription`. Removing `toolname` or `tooldescription` unregisters the tool. Each field `name` becomes a property in the input schema. Text inputs map to strings, select options map to an enum, and `required` fields go in the `required` list. Without `toolparamdescription`, the browser uses the label text.

```text
<form toolname="contact_support"
      tooldescription="Send a message to the support team."
      action="/contact" method="post">
  <label for="email">Your email</label>
  <input id="email" name="email" type="email" required>
  <label for="message">Message</label>
  <textarea id="message" name="message" toolparamdescription="What the user needs help with"></textarea>
  <button type="submit">Send</button>
</form>
```

Without `toolautosubmit`, the user must click Submit. Leave it off. Annotate only forms that are safe for an agent to submit, such as search and contact forms. Do not annotate payment or account deletion forms. In the submit handler, `event.agentInvoked` is true for agent calls, and `event.respondWith(promise)` returns a result to the agent.

Lighthouse has a `webmcp-schema-validity` audit. It fails when a form has `tooldescription` without `toolname`, or the reverse, and when a required field has no `name`. It warns when an optional named field has neither `toolparamdescription` nor a label.

### WordPress, Shopify and static sites

Add the attributes to the form markup. In a WordPress theme, the search form lives in `searchform.php` or the Search block output. In Shopify, edit the theme file that holds the search form. Forms created by a plugin or an app may offer no way to add attributes. In that case leave them alone. SeenLens ignores forms that post to another site.

## How do I verify the fix?

1. Scan the page with SeenLens. The evidence lines show the form counts, registerTool call sites and the entry points found.
2. In Chrome with the flag or origin trial, open DevTools and look for the registered tools. Chrome documents a WebMCP panel and an inspector extension.
3. Run Lighthouse with the Agentic Browsing category. See [Lighthouse agentic audit failures](https://seenlens.com/fixes/lighthouse-agentic-audit-failures).

## When can I skip WebMCP?

Skip it if your page has no actions an agent could call. A content page with no forms gets 'not applicable'. The checks have low weights: 2, 1 and 1 in the agent readiness dimension. The standard may change, and the work needs a browser test. Fix crawler access and content first.

[Scan your page with SeenLens](https://seenlens.com/)

## Which checks are related?

- [Lighthouse agentic audit failures](https://seenlens.com/fixes/lighthouse-agentic-audit-failures) covers the Lighthouse WebMCP audits.
- [agent-card.json and other .well-known files](https://seenlens.com/fixes/well-known-agent-files) covers files for agents you operate as services.
- [WebMCP guide](https://seenlens.com/guides/webmcp) explains the concept in depth.

## Sources

- [WebMCP draft specification](https://webmachinelearning.github.io/webmcp/) (Draft Community Group Report dated 2026-11-02; document.modelContext, registerTool, annotations, security section; checked 2026-11-06)
- [Chrome for Developers: WebMCP](https://developer.chrome.com/docs/ai/webmcp) (status, origin trial from Chrome 149, flag, tool design; updated 2026-10-07; checked 2026-11-06)
- [Chrome for Developers: WebMCP imperative API](https://developer.chrome.com/docs/ai/webmcp/imperative-api) (registerTool example, annotations, unregistering; checked 2026-11-06)
- [Chrome for Developers: WebMCP declarative API](https://developer.chrome.com/docs/ai/webmcp/declarative-api) (toolname, tooldescription, toolautosubmit, toolparamdescription, agentInvoked, respondWith; checked 2026-11-06)
- [Chrome for Developers: Building secure WebMCP tools](https://developer.chrome.com/docs/ai/webmcp/secure-tools) (consequentialHint, untrustedContentHint, readOnlyHint; checked 2026-11-06)
- [Chrome for Developers: Lighthouse webmcp-schema-validity](https://developer.chrome.com/docs/lighthouse/agentic-browsing/webmcp-schema-validity) (failure and warning conditions; checked 2026-11-06)