analyze_url
Analyze a web page's screen-reader navigation cost. Receive scored findings on discoverability, reachability, and operability of interactive targets.
Instructions
Analyze a web page for screen-reader navigation cost. Returns scored findings showing how hard it is for AT users to discover, reach, and operate interactive targets. Navigates to the URL in a sandboxed browser. Probes test keyboard behavior but do not submit forms or modify data.
Recommended: Use format='sarif' for concise, actionable output (~4KB). SARIF auto-filters to findings that need attention (moderate and worse). JSON/markdown include every target and can be 100x larger.
SPAs (React, Next.js, etc.): Pass waitForSelector (e.g., '[data-testid="app"]' or 'main') so Tactual waits for the app to hydrate before capturing.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to analyze | |
| profile | No | AT profile ID (generic-mobile-web-sr-v0, nvda-desktop-v0, jaws-desktop-v0, voiceover-ios-v0, talkback-android-v0) | generic-mobile-web-sr-v0 |
| device | No | Playwright device name for emulation (e.g., 'iPhone 14') | |
| explore | No | Explore hidden branches (menus, tabs, dialogs). Use with format='sarif' to avoid output overflow. | |
| exploreDepth | No | Max exploration depth (default: 2). How many levels of branches to walk when explore=true. Higher = more thorough, but each level multiplies action count. CLI defaults to 3 for power-user runs; MCP defaults to 2 for tighter agent-loop latency. | |
| exploreBudget | No | Max total actions during exploration across all branches (default: 30). Prevents pathological pages from exploding probe time. CLI default is 50; MCP default is 30 for tighter agent-loop latency. | |
| exploreTimeout | No | Total exploration timeout in ms; includes initial/revealed probe time when probe is enabled (default: 60000). | |
| exploreMaxTargets | No | Max accumulated targets before exploration stops early (default: 2000). | |
| allowAction | No | Glob patterns for controls that should be explorable despite the safety policy. | |
| format | No | Output format. 'sarif' (recommended) filters to actionable findings only. | sarif |
| minSeverity | No | Only include findings at this severity or worse. Reduces output size. | |
| waitForSelector | No | CSS selector to wait for before capturing (essential for SPAs). | |
| waitTime | No | Additional ms to wait after page load. | |
| timeout | No | Page load timeout in ms | |
| focus | No | Only analyze targets within these landmarks. | |
| excludeSelector | No | CSS selectors to hide from analysis (set aria-hidden before capture). | |
| scopeSelector | No | CSS selectors that define the subtree(s) to capture, score, and probe. | |
| exclude | No | Glob patterns to exclude targets by name/role/kind. | |
| maxFindings | No | Maximum detailed findings to return. | |
| probe | No | Run keyboard probes on interactive targets. Adds ~30-60s. | |
| probeBudget | No | Maximum number of targets for the generic probe. Overrides probeMode's generic budget. | |
| probeMode | No | Probe depth preset: fast=5/5/3/5, standard=20/20/10/20 (default), deep=50/40/20/40. Budgets are generic/menu/modal/widget. | standard |
| probeSelector | No | CSS selectors that narrow probes without changing capture/scoring. | |
| entrySelector | No | Activate this trigger before capture/probe, then prioritize newly revealed targets. | |
| goalTarget | No | Exact-ish target id, name, role, kind, or selector hint for goal-directed probing. | |
| goalPattern | No | Glob pattern matched against target id/name/role/kind/selector for goal-directed probing. | |
| probeStrategy | No | Probe family intent preset. Default all; use overlay, form, composite-widget, navigation, modal-return-focus, or menu-pattern to spend budget on one class of behavior. | |
| summaryOnly | No | Return compact summary stats. Use for quick page health checks. | |
| includeStates | No | Include captured states in JSON output for passing to trace_path's statesJson parameter. Uses compact format (~5KB). | |
| storageState | No | Path to Playwright storageState JSON (cookies + localStorage). Must be within cwd. | |
| channel | No | Browser channel: chrome, chrome-beta, msedge. Bypasses shared pool. | |
| stealth | No | Apply anti-bot-detection defaults. Pair with channel for Cloudflare-protected sites. | |
| checkVisibility | No | Run the per-icon visibility probe across profile-declared (colorScheme × forcedColors) modes. Emits hcm-icon-invisible, low-contrast-icon, and hcm-substitution-risk findings. Undefined defers to the profile default (desktop AT profiles declare the full matrix; mobile/generic do not). | |
| detectRoutes | No | Record SPA route changes (history.pushState/replaceState, popstate, hashchange) that fire during analysis. Surfaces an spa-route-changes info diagnostic when any are observed. | |
| descendFrames | No | Descend into child iframes during capture (capped at 20 frames). Appends frame targets with frame-URL attribution; Chromium can recover many inaccessible cross-origin OOPIF trees via CDP. Surfaces a frames-descended info diagnostic when any frame content is captured. | |
| autoScroll | No | Scroll to the bottom of the page in steps before capture so IntersectionObserver-driven lazy content materializes. Capped at 20 scrolls / 30 s; emits an auto-scrolled info diagnostic. | |
| dismissBanners | No | Best-effort dismiss of cookie/consent/GDPR banners. Clicks safe-accept buttons (Accept / OK / Got it / Allow all); explicitly skips Decline/Manage/Customize. Emits a banners-dismissed info diagnostic. | |
| probeHover | No | Hover candidate triggers to surface hover-only popups/tooltips without attribute hints. Diffs ariaSnapshot before/after each hover; new content becomes _hoverContent enrichment. Default budget 10 candidates; adds ~7-8 s. | |
| walkTabOrder | No | Press Tab up to 30 times and record the focused-element sequence so the analyzer can flag positive-tabindex anti-patterns and focus traps. Adds ~1-3 s. | |
| diffViewports | No | Capture the URL at desktop (1280×800) and mobile (375×667) viewports and diff the resulting target / landmark / heading lists. Surfaces a viewport-divergence diagnostic when content is set to display:none on small screens. Adds ~3-5 s. |