WebMCP declarations: tools a browsing agent can call
Which forms declare WebMCP tools with toolname and tooldescription, and which declarations are invalid. squirrel reports, and never penalises.
What WebMCP is
WebMCP is an early browser preview that lets a page offer actions to an agent that browses on behalf of a person. It is a draft from the Web Machine Learning community group, and its details can still change. A page can expose a tool two ways.
- Declaratively, a
<form>becomes a tool.toolnamegives it a name andtooldescriptionsays in plain language what it does. The input schema is derived from the form’s named controls, and a control can addtoolparamtitleandtoolparamdescription. Arequiredcontrol is a required parameter. The optional booleantoolautosubmitlets the agent submit the form without a person clicking. - Imperatively, script calls
navigator.modelContext.registerTool(...)ornavigator.modelContext.provideContext({ tools: [...] }).
Chrome’s Lighthouse agentic browsing scoring looks at the same area. Its accessibility checks overlap rules squirrel already has, so this rule links to them in Related rules instead of repeating them.
What squirrel checks
The rule runs on every crawled page and reads the raw HTML. It emits up to five checks, and none of them ever fails.
webmcp-declarative-tools: at info status,Found N declarative WebMCP tool(s) in the page HTMLwhen at least one<form>has atoolnameattribute, with one item per tool and, in the details, each tool’s name, description, parameter names and whether it autosubmits. OtherwiseNo declarative WebMCP tools, also at info status. When the page has no parsed document the check is skipped.webmcp-tool-schema: only when a tool or a straytoolnameexists. It passes when every declaration is valid, and warns otherwise with one item per problem. See Validity rules.webmcp-forms-without-tools: at info status, lists forms on the page that are not tools and that have at least one control other than a hidden input or a button. It suggests addingtoolnameandtooldescriptionto the forms that represent a task an agent should be able to do. Search and login forms are listed too: you decide which ones are tasks.webmcp-imperative: at info status, only when an inline<script>(nosrc, not a JSON type) mentionsnavigator.modelContexttogether withregisterToolorprovideContext. It says the registration was detected but not validated. External scripts and anything registered at runtime are not checked from raw HTML.webmcp-tool-form-challenge: at info status, when a tool form contains a visible challenge widget. See CAPTCHA on a tool form.
Why it is informational
The rule has info severity and weight 1. A page with no WebMCP loses nothing, because the feature is a preview that most sites do not use yet. A warn from webmcp-tool-schema is advisory and does not change the score either. The rule never emits fail.
Validity rules
webmcp-tool-schema warns when any of these is true. Only the toolname format is a squirrelscan choice: it mirrors the tool-name conventions of MCP clients, and the WebMCP draft does not fix a character set.
toolnameis empty or only whitespace.toolnameis not 1 to 64 characters of letters, digits,_,.or-. This is squirrelscan’s validity check.tooldescriptionis missing or empty.- Two forms on the page use the same
toolname. toolnameis set on an element that is not a<form>.- A
requiredcontrol, or one withtoolparamtitleortoolparamdescription, has noname, so it cannot appear in the schema. - Two controls in one tool share a
namebut have different types. A group of radio buttons or checkboxes sharing a name is fine.
Parameters are the named input, select and textarea controls inside the form. Hidden inputs, submit and reset buttons, button inputs and image inputs are not counted.
CAPTCHA on a tool form
security/form-captcha recommends a CAPTCHA on public forms, and that advice stands: keep the abuse protection. The catch is that a visible challenge on a form an agent is meant to use blocks the agent that is acting for a person. So squirrel notes a visible widget inside a tool form and suggests an invisible or agent-tolerant check there instead, such as a risk score, a rate limit, or a challenge that only appears when something looks wrong.
A widget counts as visible when it is a g-recaptcha, h-captcha, frc-captcha or cf-turnstile element. It does not count when it has data-size="invisible", when a Turnstile widget has data-appearance="interaction-only", or when the class sits on the submit <button> or <input>, which is how invisible reCAPTCHA binds. A challenge that a script adds later is not seen in raw HTML.
How to fix it
Declare a task as a tool:
<form toolname="search_flights" tooldescription="Search flights between two airports">
<input name="origin" required toolparamdescription="IATA airport code" />
<input name="destination" required />
<button type="submit">Search</button>
</form>Give every control that belongs in the schema a name, keep tool names unique on the page, and describe each tool as if the agent had never seen your site.
| Rule ID | ax/webmcp |
| Category | Agent Experience |
| Scope | Per-page |
| Severity | info |
| Weight | 1/10 |
Enable / disable
Disable this rule
[rules]
disable = ["ax/webmcp"]Disable all Agent Experience rules
[rules]
disable = ["ax/*"]Enable only this rule
[rules]
enable = ["ax/webmcp"]enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.
Check names by outcome
Each check name this rule can emit, by what it means to a tool comparing two audits. A problem check is a finding. A clean check says the rule ran over what it covers and found nothing; it clears the problem checks listed beside it, so a finding is fixed when the rule ran over the same scope and a clean check took its place. A not checked check says the rule did not evaluate, and never clears a finding.
| Check name | Outcome | Clears |
|---|---|---|
webmcp-declarative-tools | Clean | webmcp-forms-without-tools, webmcp-imperative, webmcp-tool-form-challenge |
webmcp-declarative-tools | Not checked | |
webmcp-tool-schema | Problem | |
webmcp-tool-schema | Clean | webmcp-tool-schema |
webmcp-forms-without-tools | Problem | |
webmcp-imperative | Problem | |
webmcp-tool-form-challenge | Problem |
Related rules
An agent that drives a page reads its accessibility tree, so these rules cover what a WebMCP page also needs. This rule does not repeat their findings.
- a11y/button-name: a programmatic name on every button.
- a11y/aria-input-field-name: a name on every ARIA input field.
- a11y/aria-required-children: roles that need particular children.
- a11y/aria-required-parent: roles that need a particular parent.
- a11y/aria-hidden-focus: focusable content hidden from the accessibility tree.
- a11y/aria-roles: valid role values.
- a11y/form-labels: a label on every form control.
- perf/cls-hints: layout shift that moves a control as an agent clicks it.
- security/form-captcha: the abuse protection on public forms.
References
Check your site
Run squirrel audit https://example.com and open the Agent Experience section of the report. Each tool is listed with its name and description. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.