DEV Community

Robert
Robert

Posted on

Your site just failed Lighthouse's new Agentic Browsing audit — here's how to fix each check

#webmcp #ai #webdev #seo

If you've opened Chrome DevTools lately and run Lighthouse, you may have noticed a new category sitting under Performance, Accessibility, SEO and the rest: Agentic Browsing.

It shipped in Lighthouse 13.3 (May 2026). It's still marked experimental, so it doesn't give you a 0–100 score — just a pass/fail per check. But "experimental" in Lighthouse has a way of becoming "default, and now your client is asking why it's red." So it's worth understanding now, while it's cheap.

The category answers one question: can an AI agent actually understand and operate this page? It does that with four checks. Here's what each one tests and exactly how to make it pass.

1. llms.txt

What it checks: whether your domain root serves an /llms.txt, and — this is the part people miss — whether that file is actually useful: it flags the file if it's missing an H1, is too short, or contains no links.

How to pass: add a plain-text (well, Markdown) file at https://yourdomain.com/llms.txt. Minimum viable version:

# Acme Tools

> Acme sells precision hand tools. This file helps AI agents find the right pages.

## Core pages
- [Product catalog](https://acme.example/products): browse and filter all tools
- [Search](https://acme.example/search): full-text product search
- [Support](https://acme.example/support): returns, warranty, contact
Enter fullscreen mode Exit fullscreen mode

One H1, a one-line summary, real links to the pages that matter. That's the whole check. Don't dump your sitemap into it — curate the handful of entry points an agent should know about.

2. Accessibility tree

What it checks: every interactive element has a programmatic name, roles and parent/child relationships are valid, and nothing is hidden from the a11y tree while still being interactive.

How to pass: this is just accessibility hygiene, and it's the most important check of the four — because the accessibility tree is the primary way an agent reads your page. Use real <button>, <a>, <label>/<input> pairs instead of click-handlered <div>s. Give icon-only buttons an aria-label. Make sure a <div role="button"> you couldn't avoid is focusable and named.

If you've been putting off your a11y backlog, the agentic era just gave you a second, harder-to-ignore reason to do it: the same fixes that help screen-reader users help every agent that visits.

3. Cumulative Layout Shift (CLS)

What it checks: the same CLS you already know from Core Web Vitals.

How to pass: nothing agent-specific here — reserve space for images and embeds (width/height or aspect-ratio), avoid injecting content above existing content, preload fonts. Why does an agentic category care about visual stability? Because agents that drive a real browser click coordinates and read snapshots; a page that reflows under them mis-clicks exactly like a human would. Stable layout = reliable automation.

4. WebMCP

This is the new one, and the only check that's genuinely about the agentic web rather than hygiene you should already be doing.

What it checks: Lighthouse surfaces every WebMCP tool registered on the page — whether via the declarative HTML API or imperatively through navigator.modelContext.registerTool() — and validates that any declared inputSchema is syntactically and semantically valid. For annotated forms, it checks that the annotations match the expected schema.

How to pass: you need to actually expose tools, and their schemas have to be valid. The imperative version:

if ("modelContext" in navigator) {
  navigator.modelContext.registerTool({
    name: "search_products",
    description: "Search the product catalog",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string" },
        maxPrice: { type: "number" },
      },
      required: ["query"],
    },
    // call the SAME function your search box already calls
    async execute({ query, maxPrice }) {
      const results = await productSearch({ query, maxPrice });
      return { content: [{ type: "text", text: formatResults(results) }] };
    },
  });
}
Enter fullscreen mode Exit fullscreen mode

Two things worth saying out loud, because they're where teams get this wrong:

  • Feature-detect. Most browsers don't ship navigator.modelContext yet (it's in a Chrome 149 origin trial; WebKit has formally opposed it). The if ("modelContext" in navigator) guard means you lose nothing if the spec stalls — it's progressive enhancement.
  • Reuse your existing handlers. Your search_products tool should bottom out in the exact function your search UI already calls. If a tool does something your UI can't, you've created a second source of truth that will drift — which is precisely the redundancy critique WebKit raised. Keep tools as thin, typed front doors to behavior you already ship.

The honest prioritization

Three of these four checks — llms.txt, accessibility, CLS — are things you should be doing regardless of whether you believe in the agentic web. Do them first; they pay off for users and search today.

The fourth, WebMCP, is the real bet on where browsing is going. It's also the one with the most leverage if you sell anything: the gap between "an agent can read my page" and "an agent can complete a purchase on my page" is exactly the gap WebMCP tools fill.

Disclosure: I work on Latch, an open-source (MIT) one-line script that does the WebMCP check (#4) for you — it exposes your site's existing search/cart/forms as WebMCP tools with valid schemas, feature-detected, reusing your own handlers. If you'd rather understand the standard than adopt any tool, the WebMCP guide is vendor-neutral. Happy to talk trade-offs in the comments.

Top comments (0)