# BrowserPaw Canonical Tool Reference

> Automatically generated by `scripts/gen-tools-doc.mjs` from `packages/shared/src/tools.ts`. To regenerate: `node scripts/gen-tools-doc.mjs`.

| Profile            | Tool Count | Estimated Prompt Footprint (chars/4) | Description                                                                           |
| :----------------- | :--------: | :----------------------------------: | :------------------------------------------------------------------------------------ |
| **core** (default) |     14     |                ~9.2k                 | High-frequency essentials: 1-based DOM indexing, form filling, visual actions, grep   |
| **full**           |     50     |                ~20.4k                | Complete canonical tool surface: raw CDP access, tab groups, diagnostics, performance |
| **crawl**          |     12     |                ~6.1k                 | High-throughput web extraction, markdown summarization, and media inspection          |

Canonical surface: 50 tools = 49 extension-executed tools + 1 native-server tool (`chrome_act_toward_goal`, served by the local Jev engine). Profile counts are Core 14 / Crawl 12 / Full 50. Footprints are character-based estimates (serialized schema characters / 4), not measured BPE token counts.

Tools hidden under the active profile can be inspected and dynamically activated for the session via `chrome_tool_docs` without restarting the server.

## Navigation & Tabs

### `chrome_navigate`

Navigate to a URL, refresh the current tab, or navigate browser history (back/forward)

- `url` — URL to navigate to. Special values: "back" or "forward" to navigate browser history in the target tab.
- `action:back|forward` — Alternative to url="back"|"forward": navigate browser history backward or forward.
- `newWindow` — Create a new window to navigate to the URL or not. Defaults to false
- `tabId` — Target an existing tab by ID (if provided, navigate/refresh/back/forward that tab instead of the active tab).
- `windowId` — Target an existing window by ID (when creating a new tab in existing window, or picking active tab if tabId is not provided).
- `background` — Perform the operation without stealing focus (do not activate the tab or focus the window). Default: true (set false only if user explicitly asks to bring tab to foreground)
- `width` — Window width in pixels (default: 1280). When width or height is provided, a new window will be created.
- `height` — Window height in pixels (default: 720). When width or height is provided, a new window will be created.
- `refresh` — Refresh the current active tab instead of navigating to a URL. When true, the url parameter is ignored. Defaults to false
- `groupTitle` — Concise, task-aligned title for the Chrome tab group reflecting user intent in user language (e.g. "Best 4K Monitors on Amazon", "GitHub PR Review"). If omitted, the extension derives a smart title dynamically from the destination domain and page title instead of generic fallback.
- `groupColor:grey|blue|red|yellow|green|pink|purple|cyan|orange` — Color for the Chrome tab group. Fallback: "blue"
- `autoGroup` — Automatically place newly opened tab into an Agent-managed tab group with dedicated title and color. Default: true
- `dismissOverlays` — Automatically detect and dismiss visible marketing popups, coupon modals, and promotional overlays after navigation completes (default: false)

### `chrome_switch_tab`

Switch to a specific browser tab

- `tabId` (required) — The ID of the tab to switch to.
- `windowId` — The ID of the window where the tab is located.
- `background` — If true, binds session affinity only without activating the tab in the Chrome UI or stealing user focus. Default: false

### `chrome_close_tabs`

Close one or more browser tabs

- `tabId` — Single tab ID to close (convenience alternative to tabIds array).
- `tabIds` — Array of tab IDs to close. If not provided, will close the active tab (requires confirm: true or session affinity).
- `url` — Close tabs matching this URL. Can be used instead of tabIds.
- `confirm` — Explicit confirmation required to close the active tab when tabIds or url are not specified.
- `allManagedGroups` — Close all Agent-managed tab groups and their tabs created during automation sessions. Default: false

### `chrome_move_tab`

Move one or more tabs to a new position index or to another window.

- `tabId` — Single tab ID to move (optional if tabIds provided)
- `tabIds` — Multiple tab IDs to move
- `index` (required) — Target position index in the window (0-based, or -1 for end of window)
- `windowId` — Target window ID (optional, defaults to current window)

### `chrome_attach_tab`

Explicitly attach CDP debugger and session affinity to a specific tab (by tabId) or the user's currently active tab. WARNING / SIDE EFFECT: Attaching to the user's active tab displays Chrome's debugger warning banner ('browserpaw is debugging this browser') and directly shares execution state with the user. Avoid calling unless interaction with the user's active tab is explicitly requested.

- `tabId` — The target tab ID to attach. If omitted, attaches to the user's currently active foreground tab.
- `sessionId` — Session identifier to bind affinity to this tab.

### `chrome_detach_tab`

Detach CDP debugger from the tab and release session affinity, dismissing the Chrome debugger banner.

- `tabId` — The target tab ID to detach (defaults to session bound tab or active tab).
- `sessionId` — Session identifier to release affinity from.

### `get_windows_and_tabs`

Get all currently open browser windows and tabs

## Perception & Content Extraction

### `chrome_read_dom`

Extract and prune interactive DOM tree with compact 1-based index assignment, viewport boundary filtering, and occlusion pruning. Supports scoped container targeting (selector) and noise exclusion (exclude) to eliminate full DOM dump overhead. Optional dismissOverlays closes modals and removes overlay elements.

- `selector` — CSS selector to scope parsing to a specific container/element (e.g. "#main-cart", ".dialog-box"). Only descendants and self within matching containers are indexed.
- `scope` — Alias for selector. CSS selector to scope parsing to a specific container/element (e.g. "#main-cart", ".dialog-box"). Only descendants and self within matching containers are indexed.
- `isolateModal` — When true and an active modal dialog is detected, restricts indexing to the active modal while strictly protecting portals, dropdowns, and alert containers.
- `exclude` — CSS selector(s) to exclude from parsing (e.g. "#footer, #recommendations, .ad-banner"). Matching elements and their entire subtrees are pruned.
- `viewportThreshold` — Vertical threshold in pixels for viewport boundary checking (default 1000)
- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `highlight` — Whether to visually highlight indexed elements
- `sessionId` — Optional session identifier to bind affinity to a specific tab context
- `cursor` — Pagination cursor offset for traversing very large DOM pages incrementally (default: 0)
- `limit` — Maximum number of indexed elements to return for current page cursor slice (default: unlimited)
- `maxTextLength` — Maximum text length before truncation for element text content (default: 120)
- `includeDetails` — Also return the bulky indexedElements/indexMap detail blocks (geometry, occlusion flags, safe click points). Off by default because the tree already carries index/tag/attributes/text; enable only when you need per-element rects or visibility flags.
- `viewportOnly` — When true, only index elements inside or immediately near the visible viewport (default: false)
- `activeViewportOnly` — When true, strictly constrains indexing to elements currently visible within the active viewport (threshold = 0) with horizontal/vertical frustum clipping, eliminating ghost elements from SPA wizards, carousels, and multi-step forms.
- `format:compact|html|fast` — Output format for treeString. "compact" (default) produces a concise, accessibility-tree-inspired representation without closing tags, slashing token usage by 60%+. "html" returns legacy pseudo-HTML tags. "fast" activates ultrafast atomic snapshot mode (10-30ms, <=15KB).
- `fast` — When true, activates the ultrafast atomic DOM snapshot engine (10-30ms, <=15KB payload) with WeakMap caching and native checkVisibility.
- `legacyVisibility` — When true, uses legacy visibility fallback (computedStyle display/visibility/opacity) instead of element.checkVisibility.
- `deltaOnly` — When true, returns only changed/added/removed diffs compared to the previous snapshot, saving 90%+ tokens on repeated reads.
- `dismissOverlays` — When true, automatically detects and dismisses visible marketing popups, coupon modals, and promotional overlays before indexing DOM nodes, preventing modal overlays from polluting the DOM tree (default: false)
- `virtualizeViewport` — When true (enabled by default on infinite scroll, long feeds, and waterfall pages when selector/scope is omitted), intelligently virtualizes and folds repetitive offscreen subtrees into compact summaries, drastically slashing token usage while strictly preserving visible viewport elements and key navigation.
- `flattenCards` — When true (default: true), identifies composite card containers (article, [role="article"], [role="listitem"], li) and aggregates fragmented leaf nodes into unified structured card summaries while preserving actionable link/click indices. Slashes token usage by 60%+ on eCommerce, search feeds, and news listings.

### `chrome_get_markdown`

Extract clean, structured hierarchical markdown from the active tab DOM stripped of SPA state blobs, hidden text, and scripts.

- `includeLinks` — Whether to preserve hyperlinks in markdown (default: true)
- `fit` — Content-only extraction: restrict to the main content region and strip nav/header/footer/aside/form noise before conversion (default: false)
- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `sessionId` — Optional session identifier to bind affinity to a specific tab context

### `chrome_inspect_media`

Inspect and extract high-fidelity media assets (images, canvas, captchas, icons) directly by element index or selector. Uses in-memory lossless extraction for `<img>`/`<canvas>`, with super-sampled 200%+ crop fallback for complex DOM containers.

- `index` — 1-based element index from browserpaw_read_dom
- `selector` — CSS selector fallback
- `zoom` — Super-sampling zoom factor (default: 2.0)
- `tabId` — Target tab ID

### `chrome_grep`

Search the page without dumping full DOM tree. Supports searching interactive elements (returning indices for browserpaw_interact_index), all DOM nodes, or raw visible text lines.

- `query` (required) — Search term or regex pattern
- `isRegex` — Whether to evaluate query as a regular expression (default: false)
- `searchType:interactive_only|all_dom|page_text` — Search target: "interactive_only" (default, matches clickable/fillable elements and returns indices), "all_dom" (matches all elements), "page_text" (scans visible text lines).
- `limit` — Maximum matching results to return (default: 20, max: 50)
- `autoScroll` — When true, automatically executes client-side RAF auto-scrolling to probe and detect off-screen virtualized elements (virtual list / infinite scroll streams like X/Twitter). Default: false
- `maxSteps` — Maximum scroll iterations to attempt when autoScroll is enabled (default: 10)
- `stepPx` — Pixel distance to scroll on each probing step (default: 800)
- `tabId` — Target tab ID (optional)
- `sessionId` — Session identifier for tab affinity (optional)

### `chrome_get_dropdown_options`

Get all options from a native `<select>` dropdown, ARIA combobox, or custom menu list.

- `index` — Element numeric index from browserpaw_read_dom
- `selector` — CSS selector of the dropdown or combobox
- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `sessionId` — Optional session identifier to bind affinity to a specific tab context

### `chrome_tool_docs`

Return compact parameter documentation for a category of BrowserPaw tools (navigate | perceive | act | observe | manage | crawl | diagnose | network). Use when a workflow needs a tool that is not in the current profile view.

- `category:navigate|perceive|act|observe|manage|crawl|diagnose|network` (required) — Tool category to document
- `activateForSession` — When true, dynamically exposes all tools in this category for the current MCP session without server restart. Default: false

## Interaction & Form Automation

### `chrome_act_toward_goal`

Autonomous semantic micro-loop that perceives, decides, and acts toward a natural-language goal within a local Native Server loop (~200-400ms/step). Powered by TypeSafe Jev System One (Cloud or local resident CUDA GPU/MPS). Requires configured model; fails closed when unavailable. Automatically escalates ambiguous, destructive, or complex actions back to the macro planner with pre-fetched page context.

- `goal` (required) — Natural language goal or objective to advance toward on the current page
- `tabId` — Target tab ID (optional, defaults to active tab)
- `maxSteps` — Maximum decision steps before terminating (default: 10, max: 60; heuristic capped at <= 5)
- `timeoutMs` — Total execution timeout in milliseconds (default: 90000, max: 300000)
- `textHint` — Explicit text hint to enter when typing, if not clearly quoted in goal
- `confidenceThreshold` — Minimum confidence threshold to commit an action (default: 0.55)
- `pauseBeforeKeywords` — List of keywords (e.g. ["Post", "Submit", "Pay"]). If the predicted action targets an element whose label, text, or role matches any keyword, the micro-loop suspends before execution and returns status "paused" with target element context for System 2 confirmation.
- `sessionId` — Optional session identifier to bind affinity to a specific tab context
- `sessionContext` — Optional alias for sessionId
- `pressEnter` — Whether to press Enter after filling text into an input field. When omitted, Jev judges from the task whether to fill only, fill and submit, or is unclear; an unclear answer pauses for the caller rather than submitting. An explicit value always wins.
- `mode:off|local|remote` — Optional override for the Jev semantic execution engine mode ("off", "local", or "remote"). Defaults to the mode configured in the extension popup.

### `chrome_interact_index`

Click, hover, or interact with an element using its compact 1-based numeric index from browserpaw_read_dom. When performing predictable multi-step actions (e.g. form submission or chain navigation), prefer browserpaw_batch_actions to finish in a single round-trip.

- `index` — Compact 1-based numeric index of the target element
- `coordinate` — Visual fallback coordinates in viewport/CSS pixels: { x, y } object, [x, y] point, or [ymin, xmin, ymax, xmax] bounding box (supports 0~~1.0 normalized, 0~~1000 per-mille, or absolute viewport pixels across modern vision agents).
- `coordinateSpace:viewport|screenshot` — Coordinate reference space. "viewport" (default) assumes standard CSS viewport pixels. "screenshot" scales coordinates based on the latest screenshot capture resolution.
- `autoSnap` — When clicking via coordinates or visual fallback, magnetically snap to the closest interactive element if clicked within 24px of whitespace. Default: true.
- `points` — Click sequence: dispatch a full CDP click at each viewport point with intervalMs pacing (rapid burst for moving canvas targets)
- `intervalMs` — Delay between points in the click sequence, 5-500ms (default 35)
- `action:click|hover|double_click|right_click|drag` — Interaction action to perform (default: click). "drag" requires `end` and moves from the indexed element to that target.
- `path` — Continuous drag path: an ordered array of { x, y } coordinates to smoothly drag the mouse through while pressed. Ideal for circular gestures, sliders, and drawing on canvas.
- `end` — Drag destination: { index } for an indexed element, or { coordinate: { x, y } } for a raw point. Required when action is "drag".
- `steps` — Number of intermediate mouse-move steps for drag (default 48; lower is faster, higher is smoother)
- `holdMs` — How long to hold the mouse button before dragging, in ms (default 80, range 0-3000)
- `dnd` — Use HTML5 drag-and-drop events (dragstart/dragover/drop) instead of raw mouse moves. Needed for React/HTML5 DnD lists.
- `modifiers` — Keyboard modifiers to hold during interaction
- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `waitForSettle` — Wait for DOM mutations to settle (quiet for 150ms or timeout) after interaction before returning (default: false)
- `settleTimeoutMs` — Maximum settle timeout in milliseconds (default: 1500, range: 200-10000)
- `humanize` — Simulate realistic human-like cursor trajectory with micro-jitter before clicking (default: false)
- `includeDelta` — Automatically capture and return lightweight chained snapshot (activeElement, modal status, key DOM changes) in chainedSnapshot (default: true; set false to disable)
- `sessionId` — Optional session identifier to bind affinity to a specific tab context
- `pierceOverlay` — Automatically pierce non-opaque or transient backdrop masks/loading stubs when intercepted (default: true)
- `waitForNetworkQuiescence` — Wait for in-flight network requests to settle after this interaction before returning (default: false)
- `quiescenceTimeoutMs` — Network quiescence timeout in ms (default: 2000)
- `captureNetwork` — Inline capture of network response triggered by this interaction in a single round-trip

### `chrome_fill_index`

Fill text into an input or textarea element using its compact 1-based numeric index. For single search/form submission, pass pressEnter: true to fill and submit in 1 turn without needing a separate click. When filling multiple fields or clicking submit, use browserpaw_batch_actions to pipeline in 1 turn.

- `index` (required) — Compact 1-based numeric index of the target element
- `text` — Text content to fill into the element
- `value` — Alias for text parameter
- `clear` — Whether to clear existing field content before typing (default: true)
- `pressEnter` — Whether to dispatch an Enter key event immediately after filling the text (default: false). Strongly recommended for search boxes and single-input queries to trigger immediate submission in 1 turn.
- `submit` — Whether to automatically submit the form after filling (default: false). If true, clicks the detected submit button or presses Enter, completing fill + submit in 1 turn.
- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `waitForSettle` — Wait for DOM mutations to settle after filling text before returning (default: false)
- `settleTimeoutMs` — Maximum settle timeout in milliseconds (default: 1500, range: 200-10000)
- `includeDelta` — Automatically capture and return lightweight chained snapshot (activeElement, modal status, key DOM changes) in chainedSnapshot (default: true; set false to disable)
- `sessionId` — Optional session identifier to bind affinity to a specific tab context

### `chrome_keyboard`

Simulate keyboard input on a web page. Supports single keys (Enter, Tab, Escape), key combinations (Ctrl+C, Ctrl+V), and text input. Can target a specific element or send to the focused element.

- `keys` (required) — Keys or key combinations to simulate. Examples: "Enter", "Tab", "Ctrl+C", "Shift+Tab", "Hello World".
- `index` — Target element index (1-based integer from browserpaw_read_dom) to focus before sending keyboard events.
- `selector` — CSS selector or XPath for target element to receive keyboard events.
- `selectorType:css|xpath` — Type of selector (default: "css").
- `delay` — Delay between keystrokes in milliseconds (default: 50).
- `tabId` — Target tab ID. If omitted, uses the current active tab.
- `windowId` — Window ID to select active tab from (when tabId is omitted).
- `frameId` — Target frame ID for iframe support.
- `sessionId` — Optional session identifier to bind affinity to a specific tab context

### `chrome_upload_file`

Upload files to web forms with file input elements using Chrome DevTools Protocol

- `tabId` — Target tab ID (default: active tab)
- `windowId` — Target window ID to pick active tab when tabId is omitted
- `selector` — CSS selector for the file input element (optional if index is provided)
- `index` — Compact 1-based numeric index of the file input element from browserpaw_read_dom
- `clickTargetIndex` — Compact 1-based numeric index of a button/element from browserpaw_read_dom to click that triggers a dynamic file chooser dialog (e.g. Ant Design, Element Plus upload buttons) intercepted via CDP Page.setInterceptFileChooserDialog
- `filePath` — Local file path to upload
- `fileUrl` — URL to download file from before uploading
- `base64Data` — Base64 encoded file data to upload
- `fileName` — Optional filename when using base64 or URL (default: "uploaded-file")
- `multiple` — Whether the input accepts multiple files (default: false)
- `sessionId` — Optional session identifier to bind affinity to a specific tab context

### `chrome_insert_media`

Injects an image or media asset from local disk, URL, or base64 into a rich-text composer (e.g. Reddit, Twitter/X, Notion, Discord, Slack, GitHub) or targeted element via synthesized ClipboardEvent("paste") and DragEvent("drop") containing a real File object in DataTransfer, bypassing browser clipboard security sandboxes.

- `filePath` — Absolute or relative path to the image or media file on local disk (e.g. "C:\Users\...\diagram.png" or "/home/.../photo.jpg")
- `fileUrl` — Remote HTTP/HTTPS URL to fetch the image or media asset from
- `base64Data` — Base64-encoded media data string, optionally with "data:`<mime>`;base64," prefix
- `fileName` — Optional filename to associate with the injected file (e.g. "architecture.png")
- `mimeType` — MIME type of the media (e.g. "image/png", "image/jpeg", "image/gif", "image/webp", "image/svg+xml"). Auto-detected if omitted.
- `index` — 1-based compact element index from browserpaw_read_dom targeting the rich-text editor or composer. Defaults to active element or discovered composer.
- `selector` — CSS selector for the target container (optional fallback for index)
- `tabId` — Target tab ID (optional, defaults to active tab)
- `windowId` — Target window ID (optional)
- `sessionId` — Session identifier for tab affinity binding
- `sessionContext` — Optional alias for sessionId

### `chrome_handle_dialog`

Handle JavaScript dialogs (alert/confirm/prompt) via CDP

- `action:accept|dismiss` (required) — accept: click OK and submit promptText if provided. dismiss: click Cancel.
- `promptText` — Optional prompt text when accepting a prompt
- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `sessionId` — Optional session identifier to bind affinity to a specific tab context

### `chrome_handle_download`

Wait for a browser download and return details (id, filename, url, state, size)

- `filenameContains` — Filter by substring in filename or URL
- `timeoutMs` — Timeout in ms (default 60000, max 300000)
- `waitForComplete` — Wait until completed (default true)

### `chrome_batch_actions`

Execute a sequential multi-step pipeline of browser actions in a single round-trip without waiting for intermediate model turns.

- `actions` (required) — List of actions to execute sequentially
- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `waitForSettle` — Wait for DOM mutations to settle after all actions before returning (default: false)
- `settleTimeoutMs` — Maximum settle timeout in milliseconds (default: 1500, range: 200-10000)
- `waitForNetworkQuiescence` — Wait for in-flight network requests to settle after all actions before returning (default: false)
- `quiescenceTimeoutMs` — Network quiescence timeout in ms (default: 2000)
- `includeDelta` — Automatically capture and return DOM changes caused by the batch in the delta field (default: false)
- `sessionId` — Optional session identifier to bind affinity to a specific tab context
- `captureNetwork` — Inline capture of network response triggered during batch execution in a single round-trip

### `chrome_computer`

Use a mouse and keyboard to interact with a web browser, and take screenshots.

- `tabId` — Target tab ID (default: active tab)
- `groupTitle` — Title for the Chrome tab group created or joined for this task. Agent should generate a short, task-aligned title in the user language. Default: "Agent"
- `groupColor:grey|blue|red|yellow|green|pink|purple|cyan|orange` — Color for the Chrome tab group. Default: "blue"
- `autoGroup` — Automatically place the newly opened tab into an Agent-managed tab group with dedicated title and color. Default: true
- `background` — Avoid focusing/activating tab/window for operations (best-effort). Default: true (runs quietly in background without stealing user focus)
- `dwellMs` — For click actions: milliseconds to hold the button down before release (0-2000). Use 50-150 for targets that reject instant clicks
- `action:left_click|right_click|double_click|triple_click|left_click_drag|scroll|scroll_to|type|key|fill|fill_form|hover|wait|resize_page|zoom|screenshot` (required) — Action to perform. There is no plain "click" — use left_click.
- `ref` — Element ref/index from browserpaw_read_dom. For click/scroll/scroll_to/key/type and drag end when provided; takes precedence over coordinates.
- `coordinates` — Coordinates for actions: { x, y } object, [x, y] point, or [ymin, xmin, ymax, xmax] bounding box (supports 0~~1.0 normalized, 0~~1000 per-mille, or absolute viewport pixels across modern vision agents). Interpreted in the space set by coordinateSpace (default: viewport). Required for click/scroll and as end point for drag.
- `coordinateSpace:viewport|screenshot` — Space of coordinates: viewport (default, absolute CSS pixels) or screenshot (mapped through the most recent screenshot context for this tab).
- `autoSnap` — Magnetically snap coordinate clicks to the closest interactive element if clicked within 24px of whitespace. Default: true.
- `startCoordinates` — Starting coordinates for drag action: { x, y } object, [x, y] point, or [ymin, xmin, ymax, xmax] bounding box.
- `startRef` — Drag start ref/index from browserpaw_read_dom (alternative to startCoordinates).
- `scrollDirection` — Scroll direction: up | down | left | right
- `scrollAmount` — Scroll ticks (1-10), default 3
- `text` — Text to type (for action=type) or keys/chords separated by space (for action=key, e.g. "Backspace Enter" or "cmd+a")
- `repeat` — For action=key: number of times to repeat the key sequence (integer 1-100, default 1).
- `modifiers` — Modifier keys for click actions (left_click/right_click/double_click/triple_click).
- `region` — For action=zoom: rectangular region to capture (x0,y0)-(x1,y1) in viewport pixels or row-first bounding box [ymin, xmin, ymax, xmax].
- `crop` — Alias for region: { x, y, width, height } or { x0, y0, x1, y1 }.
- `grid` — For action=zoom or action=screenshot: overlay coordinate reference grid or reticle crosshairs.
- `highClarity` — For action=screenshot or action=zoom: preserve 100% full-resolution sharpness without downsampling.
- `format:png|jpeg|webp` — Image format for action=screenshot or action=zoom.
- `quality` — Image compression quality from 0 to 100.
- `selector` — CSS selector for fill (alternative to ref).
- `value` — Value to set for action=fill (string | boolean | number)
- `elements` — For action=fill_form: list of elements to fill (ref + value)
- `width` — For action=resize_page: viewport width
- `height` — For action=resize_page: viewport height
- `appear` — For action=wait with text: whether to wait for the text to appear (true, default) or disappear (false)
- `timeout` — For action=wait with text: timeout in milliseconds (default 10000, max 120000)
- `duration` — Seconds to wait for action=wait (max 30s)
- `windowId` — Target window ID (optional)
- `sessionId` — Optional session identifier to bind affinity to a specific tab context

### `chrome_cdp_execute`

Execute raw Chrome DevTools Protocol (CDP) commands directly on a target tab. Gives advanced reasoning agents full, unconstrained, low-level browser automation capabilities (e.g. Page, DOM, Input, Runtime, Network, Emulation domains). Requires debugger permission.

- `tabId` — Target tab ID to attach and execute CDP on. Defaults to current active/affinity tab.
- `method` (required) — CDP method name (e.g. "Page.navigate", "Runtime.evaluate", "Input.dispatchMouseEvent", "DOMSnapshot.captureSnapshot").
- `params` — Parameters object passed to the CDP method.
- `timeoutMs` — Timeout in milliseconds for this CDP command. Default: 10000.

### `chrome_request_human_intervention`

Request user assistance for high-friction barriers (SMS 2FA, puzzle captcha, payment confirmation). Renders an in-page glassmorphism overlay bar with explanation, moves agent cursor to standby, and resumes cleanly when human finishes or clicks continue.

- `reason` (required) — Clear instruction explaining what the human user needs to do
- `timeoutMs` — Timeout in milliseconds (default: 60000)
- `tabId` — Target tab ID

### `chrome_undo_last_action`

Rolls back the most recent mutating action on this tab (e.g. reverts form field input to previous value, or triggers browser history back navigation for mistaken links).

- `tabId` — Target tab ID

### `chrome_form_pipeline`

Autonomously fill and advance multi-step forms / wizards (e.g. Typeform, onboarding, multi-page surveys) in a local execution loop without multi-turn LLM ping-pong. Automatically matches fields, selects choices, triggers step advancement (via Enter or OK/Next button), and yields structured interrupts upon CAPTCHA or blocking validation errors.

- `fields` (required) — Ordered list of fields and values to fulfill throughout the form flow
- `maxSteps` — Maximum form advancement steps to attempt before returning (default: 20)
- `autoAdvance` — Automatically trigger step advance via Enter or clicking OK/Next button after input (default: true)
- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `sessionId` — Optional session identifier to bind affinity to a specific tab context
- `sessionContext` — Optional alias for sessionId

### `chrome_dismiss_overlay`

Fast 1-step dismissal for visible high-z-index marketing popups, coupon dialogs, promotional banners, and cookie consent overlays (e.g. promotional banners, modals with "Close", "Skip", "Cancel", "×"). Locates close buttons and dismisses top-level dialogs without dumping hundreds of DOM nodes or wasting roundtrips.

- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `maxOverlays` — Maximum number of stacked overlays to dismiss (default: 5)
- `waitForSettle` — Wait for DOM settle after dismissal (default: true)
- `settleTimeoutMs` — Maximum time in milliseconds to wait for page settle (default: 1500)
- `sessionId` — Session ID for tab affinity routing
- `sessionContext` — Session context alias

## Observation & Scrolling

### `chrome_screenshot`

[Prefer browserpaw_read_dom over taking a screenshot] Take a screenshot of the current page or a specific element. Returns base64 image directly in MCP image content block without writing to disk. By default, output is compressed JPEG with maxWidth <= 1280px. Debug disk save is available via savePng/saveToDisk into system temporary directory.

- `name` — Name or label for the screenshot. Purely in-memory by default; only written to disk if savePng/saveToDisk is explicitly set to true.
- `selector` — CSS selector for element to screenshot
- `assetIndex` — View one visual asset listed by browserpaw_read_dom ([asset N] lines): returns the real image resource; falls back to a viewport crop when bytes are unavailable
- `tabId` — Target tab ID to capture from (default: active tab).
- `windowId` — Target window ID to pick active tab from when tabId is not provided.
- `background` — Attempt capture without bringing tab/window to foreground. CDP-based capture is used for viewport captures. Default: true
- `width` — Width in pixels (default: 800)
- `height` — Height in pixels (default: 600)
- `maxWidth` — Maximum width in pixels for compression (default: 1280)
- `storeBase64` — Return screenshot in base64 format in text content (image content is always returned directly)
- `fullPage` — Capture a full-page scroll screenshot with GoFullPage-grade industrial stitching: automatic StyleStack fixed/sticky header de-duplication, page warmup for lazy-loading/skeletons, dynamic height change recovery, and captureVisibleTab quota backoff retry (default: false).
- `maxHeight` — Maximum height in pixels to capture for full-page screenshots (default: 50000, protects against infinite scroll runaway).
- `savePng` — Save screenshot to system temporary directory for debugging (default: false, zero disk write by default)
- `saveToDisk` — Deprecated alias for savePng (default: false, zero disk write by default; saves to system temp, not Downloads). Prefer savePng.
- `som` — Overlay Set-of-Mark numbered badges on interactive elements before capturing the screenshot
- `highlight` — Deprecated alias for som; still accepted but hidden from the schema to keep it small. Prefer som.
- `targetIndex` — Compact 1-based numeric index of target element from browserpaw_read_dom to crop and capture only this specific region of interest
- `index` — Alias for targetIndex: compact 1-based numeric index of target element from browserpaw_read_dom to crop and capture
- `padding` — Padding in pixels to expand around targetIndex crop area (default: 0)
- `region` — Lossless high-density ROI crop: capture only a specific sub-region { x0, y0, x1, y1 } in CSS pixels or polymorphic [ymin, xmin, ymax, xmax]. Completely avoids downscaling and preserves full pixel clarity for fine details like small text or dice dots.
- `crop` — Alias for region: { x, y, width, height } or { x0, y0, x1, y1 }.
- `grid` — Overlay semi-transparent coordinate reference grid with perimeter tape measure rulers (20/50/100px ticks) and interior reticle crosshairs (+) to eliminate visual estimation hallucination (default: false)
- `enableGrid` — Alias for grid: overlay semi-transparent coordinate reference grid with perimeter tape measure rulers and crosshairs
- `expandSearchArea` — For small elements (< 100x100), adaptively expand the crop bounding box to preserve surrounding headers and text context (default: true)
- `format:png|jpeg|webp` — Image output format: webp (default, high compression for LLM), jpeg, or png
- `quality` — Image compression quality from 0 to 100 for webp/jpeg formats (default: 80)
- `highClarity` — Prioritize 100% full-resolution clarity without downsampling (disables dimension scaling, keeps 1:1 CSS pixel sharpness for reading fine details or dice dots).
- `sessionId` — Optional session identifier to bind affinity to a specific tab context

### `chrome_smart_scroll`

Intelligently detects and scrolls the most prominent scrollable container on the page, or targets a specific container by selector, ref, or coordinate with automatic progress calculation.

- `tabId` — Target tab ID (optional)
- `sessionId` — Session ID for tab affinity (optional)
- `direction:down|up|left|right` — Scroll direction (default: "down")
- `amount` — Scroll amount: number in pixels, "page" (viewport height), or "half_page" (default: "page")
- `selector` — Optional CSS selector of the scroll container to target
- `ref` — Optional 1-based numeric index of the scroll container to target
- `index` — Alias for ref: 1-based numeric index of the scroll container to target
- `coordinate` — Optional coordinate to locate the scrollable container under pointer: { x, y } object, [x, y] point, or [ymin, xmin, ymax, xmax] bounding box
- `smooth` — Whether to use smooth scrolling behavior (default: true)
- `waitForSettle` — Wait for DOM and network activity to settle after scroll completes (default: true)
- `settleTimeoutMs` — Maximum settle wait timeout in ms (default: 1500)
- `note` — Optional intent note displayed on virtual agent cursor during scrolling (e.g. "Scrolling down timeline")

### `chrome_scroll_until_found`

Performs automated client-side RAF auto-scrolling and live DOM / Shadow-DOM detection to locate target text, regex, or selector without multi-turn LLM polling loops. Designed specifically for infinite scroll and virtualized feeds (e.g. X/Twitter, Reddit, Weibo). Immediately stops when target appears, centers element in viewport, and returns its 1-based interactive index.

- `query` — Text string or regex pattern to search for during scrolling.
- `isRegex` — Whether to evaluate query as a regular expression (default: false).
- `selector` — CSS selector for the target element (supports Shadow DOM piercing combinators like >>>).
- `role` — ARIA role to filter matching elements (e.g. "button", "article", "link").
- `direction:down|up` — Scroll direction (default: "down").
- `stepPx` — Pixel offset to scroll on each step (default: 800).
- `maxSteps` — Maximum scroll iterations before stopping (default: 10, max: 30).
- `scrollDelayMs` — Pause duration in ms after each step to allow virtual list rendering (default: 250ms). Alias for settleMs.
- `settleMs` — Pause duration in ms after each step to allow virtual list rendering (default: 150ms).
- `timeoutMs` — Total maximum time in milliseconds to scroll before stopping (default: 15000, max: 60000).
- `containerSelector` — Optional CSS selector of specific scrollable container instead of window/document.
- `actionOnFound:none|scroll_into_view|click|focus` — Action to perform automatically when element is found (default: "scroll_into_view").
- `tabId` — Target tab ID (optional).
- `windowId` — Target window ID (optional).
- `sessionId` — Session identifier for tab affinity (optional).
- `sessionContext` — Session context alias (optional).

### `chrome_console`

Capture console output from a browser tab. Supports snapshot mode (default; one-time capture with ~50ms settle wait), buffer mode (persistent per-tab buffer you can read/clear instantly without waiting), and stop mode (release the persistent buffer for a tab).

- `url` — URL to navigate to and capture console from. If not provided, uses the current active tab
- `tabId` — Target an existing tab by ID (default: active tab).
- `windowId` — Target window ID to pick active tab when tabId is omitted.
- `background` — Do not activate tab/focus window when capturing via CDP. Default: true
- `includeExceptions` — Include uncaught exceptions in the output (default: true)
- `maxMessages` — Maximum number of console messages to capture in snapshot mode (default: 100). If limit is provided, it takes precedence.
- `mode:snapshot|buffer|stop` — Console capture mode: snapshot (default; one-time capture with a ~50ms settle wait), buffer (persistent per-tab buffer; reads from memory instantly), or stop (stop the persistent buffer for this tab and release its resources; idempotent).
- `buffer` — Deprecated alias for mode="buffer". Prefer mode.
- `clear` — Buffer mode only: clear the buffered logs for this tab before reading (default: false). Use clearAfterRead instead to clear after reading (mcp-tools.js style). Ignored by stop mode, which discards the buffer entirely.
- `clearAfterRead` — Buffer mode only: clear the buffered logs for this tab AFTER reading, to avoid duplicate messages on subsequent calls (default: false). This matches mcp-tools.js behavior.
- `pattern` — Optional regex filter applied to message/exception text. Supports /pattern/flags syntax.
- `onlyErrors` — Only return error-level console messages (and exceptions when includeExceptions=true). Default: false.
- `limit` — Deprecated alias for maxMessages. Prefer maxMessages.

## Data & Tab Management

### `chrome_history`

Retrieve and search browsing history from Chrome

- `text` — Text to search for in history URLs and titles. Leave empty to retrieve all history entries within the time range.
- `startTime` — Start time as a date string. Supports ISO format (e.g., "2023-10-01", "2023-10-01T14:30:00"), relative times (e.g., "1 day ago", "2 weeks ago", "3 months ago", "1 year ago"), and special keywords ("now", "today", "yesterday"). Default: 24 hours ago
- `endTime` — End time as a date string. Supports ISO format (e.g., "2023-10-31", "2023-10-31T14:30:00"), relative times (e.g., "1 day ago", "2 weeks ago", "3 months ago", "1 year ago"), and special keywords ("now", "today", "yesterday"). Default: current time
- `maxResults` — Maximum number of history entries to return. Use this to limit results for performance or to focus on the most relevant entries. (default: 100)
- `excludeCurrentTabs` — When set to true, filters out URLs that are currently open in any browser tab. Useful for finding pages you've visited but don't have open anymore. (default: false)

### `chrome_bookmark_search`

Search Chrome bookmarks by title and URL

- `query` — Search query to match against bookmark titles and URLs. Leave empty to retrieve all bookmarks.
- `maxResults` — Maximum number of bookmarks to return (default: 50)
- `folderPath` — Optional folder path or ID to limit search to a specific bookmark folder. Can be a path string (e.g., "Work/Projects") or a folder ID.

### `chrome_bookmark_add`

Add a new bookmark to Chrome

- `url` — URL to bookmark. If not provided, uses the current active tab URL.
- `title` — Title for the bookmark. If not provided, uses the page title from the URL.
- `parentId` — Parent folder path or ID to add the bookmark to. Can be a path string (e.g., "Work/Projects") or a folder ID. If not provided, adds to the "Bookmarks Bar" folder.
- `createFolder` — Whether to create the parent folder if it does not exist (default: false)

### `chrome_bookmark_delete`

Delete a bookmark from Chrome

- `bookmarkId` — ID of the bookmark to delete. Either bookmarkId or url must be provided.
- `url` — URL of the bookmark to delete. Used if bookmarkId is not provided.
- `title` — Title of the bookmark to help with matching when deleting by URL.

### `chrome_tab_group_create`

Create a new tab group with specified tabs or add tabs to an existing group.

- `tabIds` (required) — Array of tab IDs to add to the group
- `groupId` — Optional existing group ID to add tabs into
- `title` — Optional title label for the tab group
- `color:grey|blue|red|yellow|green|pink|purple|cyan|orange` — Optional color for the tab group
- `collapsed` — Whether the tab group should be collapsed (default: false)
- `windowId` — Target window ID (optional)

### `chrome_tab_group_update`

Update properties (title, color, collapsed state) of an existing tab group.

- `groupId` (required) — The ID of the tab group to update
- `title` — New title for the tab group
- `color:grey|blue|red|yellow|green|pink|purple|cyan|orange` — New color for the tab group
- `collapsed` — Whether the group should be collapsed

### `chrome_tab_group_list`

List all open tab groups in the browser or within a specific window.

- `windowId` — Optional window ID to filter groups by
- `title` — Optional group title to filter by

### `chrome_tab_group_ungroup`

Remove one or more tabs from their current tab group.

- `tabIds` (required) — Array of tab IDs to ungroup

### `chrome_tab_group_close`

Close all tabs in a tab group and delete the group.

- `groupId` (required) — The ID of the tab group to close

## Diagnostics & Debugging

### `chrome_doctor`

Diagnose BrowserPaw environment, Native Host connectivity, Chrome silent-debugger flags, port availability, and token security.

- `verbose` — Return full path and configuration details (default: false)

### `chrome_javascript`

Execute JavaScript code in a browser tab and return the result. Built-in "mcp" helper supports end-to-end in-page agent workflows: mcp.run(async () => ...), mcp.waitFor, mcp.click, mcp.fill, mcp.check, mcp.sleep, mcp.queryAll, and :has-text("...") pseudo-selector support, eliminating multi-turn LLM ping-pong latency. Uses CDP Runtime.evaluate with awaitPromise and returnByValue; automatically falls back to chrome.scripting.executeScript if the debugger is busy. Output is sanitized (sensitive data redacted) and truncated by default.

- `code` (required) — JavaScript code to execute. Runs inside an async function body, so top-level await and "return ..." are supported.
- `tabId` — Target tab ID. If omitted, uses the current active tab.
- `timeoutMs` — Execution timeout in milliseconds (default: 15000).
- `maxOutputBytes` — Maximum output size in bytes after sanitization (default: 51200). Output exceeding this limit will be truncated.

### `chrome_storage`

Read localStorage, sessionStorage, and cookies for the current tab. Cookies include HttpOnly entries that document.cookie cannot see.

- `types` — Which stores to read (default: all three)
- `filter` — Only return entries whose key or value contains this substring (case-insensitive)
- `limit` — Maximum entries returned per store (default 200)
- `includeHttpOnly` — Include HttpOnly cookies (default true). Their values are redacted (valueIncluded: false) regardless; set includeHttpOnly:false to drop the entries entirely
- `tabId` — Target tab ID (optional)
- `windowId` — Target window ID (optional)
- `sessionId` — Session ID for tab affinity (optional)

### `chrome_intercept_api`

Intercepts backend JSON API responses matching a URL pattern (e.g. "_/api/v1/data_") via CDP Network domain, bypassing messy HTML DOM scraping to obtain 100% structured ground-truth data.

- `urlPattern` (required) — Glob pattern to match API endpoint URL
- `triggerAction:inspect_recent|wait_next` — Wait for next response or inspect most recent match (default: inspect_recent)
- `timeoutMs` — Timeout in milliseconds (default: 10000)
- `tabId` — Target tab ID

### `performance_start_trace`

Starts a performance trace recording on the selected page. Optionally reloads the page and/or auto-stops after a short duration.

- `reload` — Determines if, once tracing has started, the page should be automatically reloaded (ignore cache).
- `autoStop` — Determines if the trace should be automatically stopped (default false).
- `durationMs` — Auto-stop duration in milliseconds when autoStop is true (default 5000).

### `performance_stop_trace`

Stops the active performance trace recording on the selected page.

- `saveToDownloads` — Whether to save the trace as a JSON file in Downloads (default true).
- `filenamePrefix` — Optional filename prefix for the downloaded trace JSON.

### `performance_analyze_insight`

Provides a lightweight summary of the last recorded trace. For deep insights (CWV, breakdowns), integrate native-side DevTools trace engine.

- `insightName` — Optional insight name for future deep analysis (e.g., "DocumentLatency"). Currently informational only.
- `timeoutMs` — Timeout for deep analysis via native host (milliseconds). Default 60000. Increase for large traces.

## Network Interception & Capture

### `chrome_network_request`

Send a network request from the browser with cookies and other browser context

- `url` (required) — URL to send the request to
- `method` — HTTP method to use (default: GET)
- `headers` — Headers to include in the request
- `body` — Body of the request (for POST, PUT, etc.)
- `timeout` — Timeout in milliseconds (default: 30000)
- `formData` — Multipart/form-data descriptor. If provided, overrides body and builds FormData with optional file attachments. Shape: { fields?: Record<string,string|number|boolean>, files?: Array<{ name: string, fileUrl?: string, filePath?: string, base64Data?: string, filename?: string, contentType?: string }> }. Also supports a compact array form: [ [name, fileSpec, filename?], ... ] where fileSpec may be url:, file:, or base64:. Note: filePath and the file: spec are read through the native host, which only accepts files strictly inside its temp directory (<os.tmpdir()>/chrome-mcp-uploads) and at most 700KB (Native Messaging 1MB pipe, base64 inflates binary by 33%). For arbitrary local paths use browserpaw_upload_file or browserpaw_insert_media.
- `tabId` — Optional ID of the tab to execute the request within (defaults to active tab)
- `tabUrl` — Optional URL of the tab to execute the request within
- `sessionId` — Optional session identifier to bind affinity to a specific tab context
- `sessionContext` — Optional alias for sessionId

### `chrome_network_capture`

Unified network capture tool. Use action="start" to begin capturing, action="stop" to end and retrieve results. Set needResponseBody=true to capture response bodies (uses Debugger API, may conflict with DevTools). Default mode uses webRequest API (lightweight, no debugger conflict, but no response body).

- `action:start|stop` (required) — Action to perform: "start" begins capture, "stop" ends and returns results
- `needResponseBody` — When true, captures response body using Debugger API (default: false). Only use when you need to inspect response content.
- `url` — URL to capture network requests from. For action="start". If not provided, uses the current active tab.
- `maxCaptureTime` — Maximum capture time in milliseconds (default: 180000)
- `inactivityTimeout` — Stop after inactivity in milliseconds (default: 60000). Set 0 to disable.
- `includeStatic` — Include static resources like images/scripts/styles (default: false)