If you've recently run a Lighthouse audit or tested your page in PageSpeed Insights and come across a warning about WebMCP form coverage, you're probably wondering if you broke something. You didn't. This is a new check, part of the WebMCP category, that flags forms without declarative annotations and suggests how to make them easier for AI agents to use. In this article we explain exactly what Lighthouse checks, which attributes actually exist in the specification, and how to fix the issue without introducing other risks.
What the WebMCP form coverage check in Lighthouse is
WebMCP form coverage is an audit in Lighthouse's WebMCP category, designed to identify HTML forms on a page that lack declarative annotations for AI agents. The full message that shows up in the report is: "Consider adding WebMCP annotations to the forms listed below. This helps AI agents identify and interact with these forms more reliably."
In practice, Lighthouse scans every <form> element on the page and checks whether it has been explicitly described through dedicated attributes, so that an automated agent can quickly understand the form's purpose without trying to guess from labels, placeholders, or visual context what the form actually does.
Where this warning shows up
The check appears both in Lighthouse run directly from DevTools, under the Lighthouse tab, and in reports generated by PageSpeed Insights, under the dedicated WebMCP section. It's not tucked away in some obscure subcategory, it's clearly visible, with forms listed individually, each linked to its element in the DOM.
It's worth noting that this WebMCP category is fairly new within the Lighthouse ecosystem and keeps expanding. As the WebMCP specification stabilizes, you might see additional checks added to the same category, but the basic principle stays the same: identifying interactive elements that aren't described for agents.
What the Unscored label means
Next to the check's title you'll see the label "Unscored." This means the check is diagnostic, not scored. It doesn't affect the page's overall performance, accessibility, or SEO score. It's simply a recommendation, similar to other diagnostic audits in Lighthouse that don't move the final number but still provide useful information.
If you saw this warning and panicked thinking your score suddenly dropped, you can relax: it's unrelated. The forms listed aren't technically "wrong," they work perfectly fine for human users. The check simply flags an opportunity to improve interaction with AI agents, not an error that needs urgent fixing.
What Lighthouse actually checks
Specifically, the audit looks at each form on the page for the presence of WebMCP declarative attributes. If a form has none of these attributes, it gets listed as lacking coverage. It doesn't check the form's semantic validity, doesn't check accessibility, and doesn't check whether the form submits data correctly, it strictly checks for the presence of annotations for agents.
Small, single-field forms are flagged just as much as complex forms with many fields and validation logic. A simple search form, a newsletter signup form, or a full contact form, all show up on the list if they haven't been annotated.
The real attributes from Chrome's specification
This is where most of the confusion happens, because there are articles circulating online that mention attributes that don't actually exist. According to the current WebMCP specification from Chrome, the real declarative attributes are the following:
toolname, applied to the<form>element, giving a short, clear name to the tool exposed by the form.tooldescription, also on the form, explaining in natural language what that form does.toolparamdescription, applied to each field in the form, describing what that field represents and what kind of value is expected.toolautosubmit, optional, indicating that the form can be submitted automatically by the agent, without an additional confirmation step.
These are the only attributes defined in the specification for declarative annotation. There is no toolaction and no data-toolname, although both unfortunately show up in some articles and even in some improvised validators. If you use these made-up attributes, they'll simply be ignored by Lighthouse and by browsers implementing WebMCP, since they're not part of the specification.
The confusion around toolaction and data-toolname
This confusion usually comes from two sources. The first is the habit, inherited from other web technologies, of prefixing custom attributes with data-. This pattern is correct for generic custom HTML attributes, but WebMCP doesn't follow this convention, its attributes are plain names without a prefix.
The second source is confusion with the term "action," which sounds natural next to a form, but there's no attribute called toolaction in the WebMCP specification. If you see this attribute mentioned somewhere, treat the information with caution and check directly with Chrome's official WebMCP documentation before implementing it, because the time spent on it won't produce any effect.
Declarative annotations versus imperative tools
Besides the declarative attributes above, the WebMCP specification also allows an imperative approach, where tools are registered directly from JavaScript, using registerTool through the modelContext object. It's important to understand the difference between the two approaches, since they have different requirements and limitations.
Declarative annotations are simple HTML attributes. They're present in the markup even if JavaScript never runs, which makes them visible even to agents that only parse the page's static HTML, without running a full rendering engine. Imperative tools, on the other hand, need the WebMCP API to be available in the browser running the page and, at the moment, a valid origin trial token enabled for your domain.
Our recommendation, confirmed by the projects we've implemented, is to use both approaches wherever possible: declarative annotations cover the basic, robust, simple case, while imperative tools allow additional logic, such as dynamic validation or conditional field completion. If you'd like an assessment of your current situation, an AI agent readiness audit can show you exactly where your pages stand relative to both levels.
How to fix it: an annotated form example
The practical fix for the WebMCP form coverage warning is simple: add the declarative attributes directly to the form and its fields. Below is a concrete example, for a product search form:
<form toolname="cautare-produse" tooldescription="Permite căutarea produselor din catalog după nume sau cod">
<label for="query">Termen de căutare</label>
<input type="text" name="query" toolparamdescription="Cuvântul cheie sau codul produsului căutat">
<label for="categorie">Categorie</label>
<select name="categorie" toolparamdescription="Categoria de produse în care se face căutarea">
<option value="">Toate categoriile</option>
<option value="electrocasnice">Electrocasnice</option>
</select>
<button type="submit">Caută</button>
</form>Notice that toolname and tooldescription are applied once, on the <form> element, while toolparamdescription is repeated for each relevant field. There's no need to annotate the submit button, the agent understands from context that it triggers submission of the already-described form.
Why you shouldn't add toolautosubmit out of habit
The toolautosubmit attribute is tempting, since it promises a smoother experience for the agent, which can fill in and submit the form in a single step, without user intervention. However, this attribute means exactly what it says: the agent can submit the form without confirmation from the person who started the conversation.
For this reason, we don't recommend using it on forms that involve:
- payments, orders, or any action that costs the user money;
- consumption of limits or quotas, such as requests to a rate-limited API or bookings with limited availability;
- messages sent to a human operator, where a misinterpretation could produce a wrong ticket or a request sent by mistake.
For a simple search form, like the one in the example above, the risk is minimal, and toolautosubmit can make sense. For checkout, contact, or booking forms, treat this attribute with caution and leave the final confirmation to the human user.
An important trap: the anti-spam honeypot
From our experience with real implementations, this is where a subtle but common problem shows up. Many contact forms use a honeypot trap field, hidden visually through CSS, meant to catch spam bots that automatically fill in every field in a form. A human user never sees this field and obviously never fills it in.
The problem arises when an AI agent, trained to conscientiously fill in every field it finds in a form, also fills in the honeypot field, just like a spam bot would. The result is that the server silently discards the request, treating it as spam, and the user who relied on the agent gets no response at all, with no idea why.
The solution is simple and doesn't compromise the anti-spam protection: give the honeypot field a clear description through toolparamdescription, explicitly telling the agent to leave that field empty. A concrete example looks like this:
<input type="text" name="website" toolparamdescription="Lăsați acest câmp complet gol, este un câmp de control tehnic, nu introduceți nicio valoare">The protection stays effective because regular spam bots don't read the toolparamdescription attribute, they fill in fields based on name and input type, ignoring any descriptive text added for agents. So the trap keeps catching automated spam, while legitimate AI agents, which follow the instructions in the annotations, leave the field empty and the user's request reaches its destination correctly.
How to verify you've fixed the issue
After adding declarative attributes to the relevant forms, the simplest way to confirm the fix is to rerun the Lighthouse audit, either from DevTools or through PageSpeed Insights. The WebMCP form coverage check should no longer list the annotated forms, or should only list the ones still missing attributes.
A faster alternative, especially if you're testing multiple pages often, is to use a validator that runs the page in a real browser, not just a static code analyzer. The free validator available on our homepage does exactly that, it renders the page, identifies the forms, and checks for the presence and correctness of the declarative attributes, giving you a clear report of what still needs adjusting.
If you're working on a larger site, with dozens of forms spread across different page categories, it's also worth checking our WebMCP implementation methodology, which describes the recommended prioritization order, from forms critical to conversion down to secondary ones.
Conclusion
The WebMCP form coverage check in Lighthouse isn't a reason to worry, it's a diagnostic recommendation, easy to fix by adding the real declarative attributes: toolname, tooldescription, toolparamdescription, and, carefully, toolautosubmit. Avoid made-up attributes like toolaction or data-toolname, be careful with forms that touch money or people, and don't forget about the honeypot trap. If you'd like a complete, verified implementation, our team can help through the WebMCP implementation service.
