pilot_snapshot
Capture an accessibility tree snapshot of a web page to reveal its structure and obtain element references for automated interaction.
Instructions
Capture an accessibility tree snapshot of the page with @eN refs for element selection. Use when the user wants to see the page structure, find elements to interact with, or get refs for click/fill/hover. This is the primary way to understand what is on the page. Refs from this snapshot are used by pilot_click, pilot_fill, pilot_hover, pilot_select_option, and most other interaction tools.
Parameters:
selector: CSS selector to scope the snapshot to a specific subtree (e.g., "#main-content")
interactive_only: Set to true to show only interactive elements (buttons, links, inputs) — saves tokens on large pages
compact: Set to true to remove empty structural nodes from the tree
depth: Limit the tree depth (0 = root only). Useful for reducing token usage on deeply nested pages
include_cursor_interactive: Set to true to scan for elements with cursor:pointer, onclick, or tabindex that are not in the ARIA tree — returns @cN refs
max_elements: Maximum elements to include before truncating (saves tokens on very large pages)
structure_only: Set to true to show tree structure without text content — saves tokens when you only need the element hierarchy
output_file: Set to true to save the snapshot to a temp file instead of returning inline. Returns the file path — read with the Read tool when needed. Useful when the snapshot is large and you only need it on demand.
Returns: Text representation of the accessibility tree with @eN refs (and @cN refs if include_cursor_interactive is true). If output_file=true: returns only the file path (e.g. /tmp/pilot-snap-abc123.txt).
Errors:
Timeout: The page is too complex or unresponsive. Try scoping with selector or using max_elements.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| selector | No | CSS selector to scope the snapshot | |
| interactive_only | No | Only show interactive elements (buttons, links, inputs) | |
| compact | No | Remove empty structural nodes | |
| depth | No | Limit tree depth (0 = root only) | |
| include_cursor_interactive | No | Scan for cursor:pointer/onclick/tabindex elements not in ARIA tree | |
| max_elements | No | Max elements to include before truncating (saves tokens on large pages) | |
| structure_only | No | Show tree structure without text content — saves tokens | |
| lean | No | Strip structural noise (empty rows/cells, separator text, duplicate labels). Default: true. Set false for raw ARIA tree. | |
| verbose | No | Alias for lean=false. Returns full ARIA tree with all structural nodes. | |
| output_file | No | Save snapshot to a temp file and return only the file path. Read with the Read tool when needed. |