execute_js
Run JavaScript in the active page to click, scroll, read, or inspect DOM elements when overlays, viewport limits, or native interaction timeouts block standard actions.
Instructions
Run JavaScript directly in the active page. PRIMARY INTERACTION TOOL: try execute_js FIRST for clicks, scrolls, reads, attribute lookups, and most other DOM work -- it bypasses overlay/obscured-element issues, viewport constraints, and CDP timeouts that block native click/scroll. Typical patterns: return document.querySelector('#add-to-cart-button').click(), true; for clicks; return Array.from(document.querySelectorAll('a')).map(a=>a.href); for extraction; window.scrollTo(0, document.body.scrollHeight); return true; for scroll. After a JS click, verify with read_page or get_page_snapshot (a true click should produce observable DOM change). FALLBACK TO NATIVE TOOLS WHEN: (1) JS click reports success but the page state did not change (framework swallowed the synthetic event -- use native click which fires real CDP events that React/Angular/Vue listen to); (2) typing into controlled text inputs (use native type so React onChange fires correctly -- element.value = ... will NOT update component state); (3) real drag operations on react-beautiful-dnd / Sortable.js / Trello-style widgets (use drag_drop / drag for real pointer events); (4) form submission that depends on validated input state (use native click on submit). Code runs as a function body -- use return to send values back (results are stringified). Async work: Promises are not awaited, so fire-and-forget then poll on window.__yourKey. Related: read_page (verify result), get_dom_snapshot (debug after JS click), click / type / drag_drop (fallbacks when JS doesn't take effect). Multi-agent: agent-scoped tabs; cross-agent reject with TAB_NOT_OWNED; cap configurable (default 8, 1-64). Pass tab_id only when this agent owns multiple tabs; auto-resolves otherwise. RETURNS change_report: when this tool runs, the response includes a change_report field with a compact diff of what the action mutated (URL, dialogs_opened, nodes_added, nodes_removed, attrs_changed, inputs_changed, focus_shift). Use this to learn the consequence without calling read_page next. If the report exceeds the size cap, change_report.truncated:true and change_report_hint are set; call read_page for the full state.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | JavaScript code to execute in the page (use `return` to send a value back, e.g., "return document.title;" or "document.querySelector('button').click()") | |
| client | Yes | Allowlisted client label. Validated against the shared v0.9.36 server/extension allowlist (see mcp/src/tools/visual-session.ts -- MCP_VISUAL_CLIENT_LABELS). Required. | |
| tab_id | No | Optional. Tab id this action targets. Omit when the calling agent owns exactly one tab; pass to disambiguate when the agent owns multiple. Single-tab agents and legacy popup/sidepanel/autopilot do not need to pass this. | |
| is_final | No | When true, the visual session clears immediately after this tool resolves. Optional (default false). | |
| visual_reason | Yes | Short human-readable reason shown in the overlay (for example, "Logging in to GitHub"). Required. |