BrowserClaw Canonical Tool Reference

September 21, 2026 · View on GitHub

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	Approximate Prompt Footprint	Description
core (default)	14	~11.5k tokens	High-frequency essentials: 1-based DOM indexing, form filling, visual actions, grep
full	49	~19.5k tokens	Complete canonical tool surface: raw CDP access, tab groups, diagnostics, performance
crawl	12	~5.8k tokens	High-throughput web extraction, markdown summarization, and media inspection

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

`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)

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 ('browserclaw 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.

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 chrome_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 chrome_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)
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 chrome_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`

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 with seamless fallback to heuristic scoring when no API key is available or on quota/network degradation. 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

`chrome_interact_index`

Click, hover, or interact with an element using its compact 1-based numeric index from chrome_read_dom. When performing predictable multi-step actions (e.g. form submission or chain navigation), prefer chrome_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 DOM changes caused by this interaction in the delta field (default: false)
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 chrome_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 DOM changes caused by filling in the delta field (default: false)
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 chrome_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 chrome_read_dom
clickTargetIndex — Compact 1-based numeric index of a button/element from chrome_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 chrome_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 chrome_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 chrome_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)
sessionId — Session ID for tab affinity routing
sessionContext — Session context alias

Observation & Scrolling

`chrome_screenshot`

[Prefer chrome_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 chrome_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 chrome_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 chrome_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)

`chrome_console`

Capture console output from a browser tab. Supports snapshot mode (default; one-time capture with ~2s wait) and buffer mode (persistent per-tab buffer you can read/clear instantly without waiting).

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 — Console capture mode: snapshot (default; waits ~2s for messages) or buffer (persistent per-tab buffer; reads from memory instantly).
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).
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 BrowserClaw 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:.
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)