Back to docs

Tool Agent Ready Audit

Test how easily AI agents can use your website. Scores your site on navigation, element discovery, and task completion.

Quick Start

npx cbrowser agent-ready-audit "https://example.com"

CLI Options

npx cbrowser agent-ready-audit "https://example.com" \
  --html                     # Generate HTML report
  --json                     # Output as JSON
  --headless                 # Run without visible browser
  --timeout 60000            # Page load timeout (ms)

MCP Tool

{
  "tool": "agent_ready_audit",
  "params": {
    "url": "https://example.com"
  }
}

Scoring Categories

Findability (35%)

Can AI agents find elements by intent?

Checks:

  • Unlabeled buttons and inputs
  • Generic button labels ("Submit" vs "Save Changes")
  • Missing form associations
  • Elements without accessible names

Stability (30%)

Will selectors still work after page changes?

Checks:

  • Dynamic class names (e.g., css-abc123)
  • Hidden select inputs (custom dropdowns)
  • Sticky overlays that block content
  • Infinite scroll patterns
  • Missing stable IDs (id, data-testid)

Accessibility (20%)

ARIA labels and semantic HTML quality.

Checks:

  • Missing ARIA labels
  • Poor heading hierarchy
  • Non-semantic interactive elements
  • Missing form labels
  • Keyboard navigation issues

Semantics (15%)

Does the page have meaningful structure for AI parsing?

Checks:

  • Missing JSON-LD structured data
  • Missing OpenGraph metadata
  • Missing llms.txt
  • Poor heading structure
  • Generic link text

Detection Functions

Function Category Severity Description
detectUnlabeledElements Findability High Buttons/inputs without names
detectGenericLabels Findability Medium Generic text like "Click here"
detectHiddenInputs Stability High Custom dropdowns hiding native selects
detectDynamicClasses Stability Medium Framework-generated class names
detectStickyOverlays Stability High Fixed elements blocking content
detectInfiniteScroll Stability Medium Endless pagination patterns
detectMissingARIA Accessibility High Interactive elements without ARIA
detectHeadingIssues Accessibility Medium Skipped or out-of-order headings
detectMissingJSONLD Semantics Medium No structured data
detectMissingOpenGraph Semantics Low No social metadata
detectMissingLlmsTxt Semantics Low No llms.txt file
detectGenericLinks Semantics Low Links with generic text
detectFormAssociations Findability High Inputs without labels
detectTouchTargets Accessibility Medium Touch targets under 44x44px
detectColorContrast Accessibility High Low contrast text
detectKeyboardTraps Accessibility High Elements that trap focus
detectTimeouts Accessibility Medium Auto-advancing content

Output Format

{
  "url": "https://example.com",
  "score": {
    "overall": 71,
    "findability": 70,
    "stability": 85,
    "accessibility": 65,
    "semantics": 60
  },
  "grade": "C",
  "summary": {
    "totalIssues": 12,
    "critical": 2,
    "high": 4,
    "medium": 4,
    "low": 2
  },
  "topIssues": [
    {
      "category": "findability",
      "severity": "high",
      "issue": "5 buttons without accessible names",
      "selector": "button.submit-btn",
      "recommendation": "Add aria-label or visible text"
    }
  ],
  "topRecommendations": [
    {
      "issue": "Custom dropdown hiding native select",
      "fix": "Use accessible combobox pattern",
      "effort": "medium",
      "impact": "high"
    }
  ],
  "duration": 3200
}

Severity Penalties

Based on Nielsen's Usability Severity Scale:

Severity Penalty Description
Critical -25 Prevents task completion
High -15 Major obstacle, hard workaround
Medium -8 Minor problem, easy workaround
Low -3 Cosmetic issue, minimal impact

Example: Fix Common Issues

Unlabeled Button

<!-- Before -->
<button><svg class="icon-search"/></button>

<!-- After -->
<button aria-label="Search">
  <svg class="icon-search" aria-hidden="true"/>
</button>

Generic Link Text

<!-- Before -->
<a href="/pricing">Click here</a>

<!-- After -->
<a href="/pricing">View pricing plans</a>

Custom Dropdown

<!-- Before (hidden select) -->
<select style="display: none">...</select>
<div class="custom-dropdown">...</div>

<!-- After (accessible combobox) -->
<div role="combobox" aria-expanded="false" aria-haspopup="listbox">
  <input aria-autocomplete="list">
  <ul role="listbox">...</ul>
</div>

Related

Copyright: (c) 2026 Alexa Eden.

License: MIT License

From the Blog