MCP Tools (Windows)

Reference for MCP tools Cua Driver exposes on Windows

This reference describes the Windows native tool registry. Other platforms: macOS MCP tools, Linux MCP tools. See MCP tool notes for shared guidance.

cua-driver exposes 57 MCP tools through a single stdio server (cua-driver mcp). Every tool is also callable from the shell as cua-driver <name> '<JSON-args>'.

Tool names are snake_case. Responses are MCP CallTool.Result envelopes: a text content block prefixed with a ✅ summary (or the error reason on failure), plus optional image or structured-content blocks on tools that produce them. See the CLI reference for CLI-specific options like --socket and --screenshot-out-file.

For the cross-cutting parameter contract (shared parameters, required-parameter rules, platform-specific parameters) and the action response shape, see MCP tool notes.

Inspection tools#

list_apps#

List Windows apps — both currently running and installed-but-not-running — with per-app state flags:

• running: is a process for this app live? (pid is 0 when false)
• active: is it the system-frontmost app? (implies running)
• kind: "desktop" for .exe-backed apps (resolved from Start-Menu shortcuts) or "uwp" for packaged store apps.
• launch_path: what launch_app would consume.

• desktop: full .exe commandline (path + any arguments preserved from the source .lnk; the exe is quoted when it contains whitespace).
• uwp: shell:appsFolder\{PackageFamilyName}!{AppId} where {AppId} falls back to App when the package manifest does not expose a specific Application.Id.

• last_used: RFC3339 mtime of the launcher (.lnk for desktop, package install location for UWP), when readable.

Running apps are derived from visible top-level windows + the foreground pid (mirrors NSApplicationActivationPolicyRegular's intent: background services and console processes are excluded). Installed apps are merged from Start-Menu .lnk enumeration and the WinRT PackageManager — running processes whose executable matches a Start-Menu target are folded into a single entry with running: true.

Use this for "is X installed?" as well as "is X running?". For per-window state — on-screen, minimized, window titles — call list_windows instead. For just opening an app — running or not — call launch_app({path: ...}) directly; list_apps is not a prerequisite.

Arguments: none.

list_windows#

List every top-level window currently known to the window manager. Each record self-contains its owning app identity so the caller never has to join back against list_apps.

Use this — not list_apps — for any window-level reasoning: "does this app have a visible window right now?", "which of this pid's windows is the main one?".

Per-record fields: window_id (HWND), pid + app_name, title, bounds {x, y, width, height}, layer (always 0), z_index (integer or null; higher values are closer to the front; null means stacking order is unavailable and callers must not infer one), is_on_screen, minimized. To select a frontmost candidate, take the maximum integer z_index; if every value is null, use an explicit fallback instead of relying on array order. The macOS-specific on_current_space / space_ids fields are omitted on Windows; current_space_id is null.

Inputs: pid (optional pid filter), on_screen_only (bool, default false).

Arguments:

• on_screen_only (boolean, optional): When true, drop windows that aren't currently on-screen. Default false.
• pid (integer, optional): Optional pid filter. When set, only this pid's windows are returned.

get_window_state#

Walk a running app's UIA tree and return BOTH a structured elements array (preferred) AND a Markdown rendering of the same tree (back-compat). Every actionable element is tagged with [element_index N] in the markdown and as element_index in the structured array — pass those indices to click, type_text, scroll, etc.

INVARIANT: call get_window_state once per turn per (pid, window_id) before any element-indexed action against that window. The index map is replaced by the next snapshot of the same (pid, window_id).

PREFERRED CONSUMERS read structuredContent.elements (one entry per indexed row with element_index, role, label, value, enabled, selected, actions (names of UIA patterns exposed as actions, omitted when empty), frame: {x,y,w,h}, parent_index, depth). The markdown tree_markdown stays available and unchanged in shape for existing text-parsing callers — but new fields will only be added to the structured side.

The UIA tree walked is the window's tree (HWND-scoped); the screenshot and window bounds reported come from the same window_id. This is the source of truth for which window the caller intends to reason about — the driver never picks a window implicitly.

window_id MUST belong to pid; the call returns isError: true otherwise. The driver does not auto-fall-back to a different window.

Set query to a case-insensitive substring to project BOTH tree_markdown and structuredContent.elements to matching rows plus their ancestor chain. Original element indices are preserved. total_element_count reports the complete snapshot; returned_element_count reports the projection.

Always returns BOTH the element tree AND a screenshot — ground on both and cross-check (the tree lies on some surfaces). Choose the modality at ACTION time: an element ax action (element_index/element_token → accessibility rung) or an element px action (x,y → pixel rung off this screenshot). capture_mode is deprecated and ignored.

The mirror image: pass include_accessibility_tree:false to SKIP the UIA walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title) — the capture-only path for a live window preview / picture-in-picture. Setting BOTH include_accessibility_tree:false and include_screenshot:false is an error. Optional max_dimension caps the returned screenshot's long edge in pixels for a cheap thumbnail.

Uses IUIAutomationCacheRequest to batch-fetch all element properties in a single COM call (Chrome's ~5000-element tree returns in ~2-3s instead of timing out at 4s with per-property RPCs).

Optional max_elements / max_depth bound the UIA walk to mitigate context-window blow-up on Electron / large web apps that produce 10k+ element trees. When applied, BOTH the markdown and the structured elements are truncated identically. Omit both for current default behaviour (≤5 000 elements, depth ≤25).

CHROMIUM COVERAGE: a browser-owned permission bubble can be composited outside the requested native window. Chromium-family snapshots therefore describe this limit in structuredContent.capture_coverage. After a verified ineffective window action, call escalate_session, take a fresh get_desktop_state snapshot, act explicitly in desktop scope if needed, then verify with another fresh desktop snapshot. This is separate from page JavaScript dialogs, which remain on browser_dialog.

Windows requires no special permissions.

Arguments:

• capture_mode (string, optional): DEPRECATED and ignored. get_window_state always returns BOTH the element tree and a screenshot — ground on both. The modality is chosen at action time by how you address the target: an element ax action (element_index/element_token) or an element px action (x,y). Any value (including the old "som"/"screenshot" aliases) is accepted but has no effect.
• include_accessibility_tree (boolean, optional): Default true — walk the UIA tree and return elements + tree_markdown alongside the screenshot. Set false to SKIP the UIA walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title) — the capture-only path for a live window preview / picture-in-picture. Mirrors include_screenshot. Setting BOTH include_accessibility_tree:false AND include_screenshot:false is an error (nothing to return).
• include_screenshot (boolean, optional): Default true — returns a grounding screenshot alongside the tree. Set false to skip the grab and return tree only (the cheap path for re-indexing before an element ax action).
• max_depth (integer, optional): Cap on the UIA-tree walk depth. Nodes whose rendered indent would exceed this are omitted. Omit for the default (25). Lower for deep menu / Electron trees. range: 1–unbounded
• max_dimension (integer, optional): Optional cap on the returned screenshot's long edge, in pixels (aspect ratio preserved) — the cheap path for a small preview. Applied on top of the configured max_image_dimension ceiling; the tighter wins. Omit for the configured default. range: 1–unbounded
• max_elements (integer, optional): Cap on the total number of UIA nodes walked. Truncates depth-first; markdown and structured elements truncate together. Omit for the default (5 000). Lower for Electron / large web apps that produce 10k+ element trees. range: 1–unbounded
• pid (integer, required): Process ID from list_apps.
• query (string, optional): Optional case-insensitive substring. Projects both tree_markdown and structured elements to matches plus ancestors while preserving original indices. Compare total_element_count with returned_element_count.
• screenshot_out_file (string, optional): When set, write the PNG to this file path instead of embedding base64 in the response. The structured output will contain screenshot_file_path instead.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• window_id (integer, required): HWND of the target window. Must belong to pid. Enumerate via list_windows or read from launch_app's windows array.

{"pid":844,"window_id":10725}

get_accessibility_tree#

Return a lightweight snapshot of the desktop: running processes and on-screen visible windows with their bounds and owner pid.

For the full UIA subtree of a single window (with interactive element indices you can click by), use get_window_state instead — this is a fast discovery read.

Arguments: none.

get_desktop_state#

Capture the full display in true screen pixels with no downscale. Use its native-size PNG as the coordinate source for actions whose target is {kind:"desktop",display_id:"primary"}. Returns the true screen size. Vision-only: no UIA tree walk.

Arguments:

• screenshot_out_file (string, optional): Write PNG here instead of base64.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.

get_screen_size#

Return the size of the main display in physical pixels plus its display scale factor. On Windows, screenshots and pixel clicks use this same physical-pixel coordinate space. Requires no special permissions.

Arguments:

• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.

get_cursor_position#

Return the current mouse cursor position in screen points (origin top-left).

Arguments:

• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.

get_config#

Report the current persistent driver config.

Pure read-only. Returns defaults when the underlying state is unset — same fallback the daemon uses at startup. Sibling to set_config.

Current schema (Windows):

{ "schema_version": 1, "version": "<crate version>", "source_sha": "<maintainer build commit or null>", "platform": "windows", "capture_mode": "ax" | "vision" (DEPRECATED, ignored), "max_image_dimension": 0 }

capture_mode is deprecated and no longer affects behavior — get_window_state always returns both the UIA tree and a screenshot.

Arguments: none.

get_recording_state#

Report the current trajectory recorder state: whether recording is enabled, the output directory (when enabled), and the 1-based counter for the next turn folder that will be written. Counter increments on every recorded action tool call and resets to 1 each time recording is (re-)enabled.

Pure read-only.

Arguments: none.

get_agent_cursor_state#

Return the session cursor's theme, semantic playback, position, visibility, and motion.

Arguments:

• session (string, required)

{"session":"example"}

Action tools#

launch_app#

Launch a Windows app hidden — the driver never brings the target to the foreground, the target's window is launched with SW_SHOWNOACTIVATE so it does not steal focus from whatever is currently frontmost.

Provide either bundle_id / name / aumid (resolved as below) or path (full path to an executable). If both name and path are given, path wins. urls opens each URL in the default browser without activating it.

Routing order: explicit aumid (or a bundle_id containing !) activates the packaged app via IApplicationActivationManager::ActivateApplication, returning the real packaged-process pid — required on Win11 for built-in apps like Notepad, Calculator, and Paint, which now ship as Microsoft Store packages where the legacy .exe in System32 is a ~7 KB stub that exits immediately. A plain name first attempts a shell:AppsFolder lookup; packaged matches use the activation manager while desktop registrations are launched through their shell parsing path. A miss falls back to ShellExecuteEx's PATH search.

Returns the launched app's pid, name, active flag, AND a windows array — same per-window shape list_windows returns. When the launch settles but no window has materialized yet (transient; rare), windows comes back empty — call list_windows(pid) explicitly a moment later. bundle_id in the response is set to the AUMID actually used for packaged-app launches and null for ShellExecuteEx launches.

Windows-only field: path (Swift uses bundle_id since macOS apps resolve via LaunchServices; Windows has no LaunchServices, so path is the canonical form). The macOS-specific webkit_inspector_port, creates_new_application_instance, and additional_arguments fields are accepted; additional_arguments is honored (forwarded as ShellExecuteEx parameters or as the AUMID activation arguments string). The remaining macOS-only fields currently no-op on Windows.

Arguments:

• additional_arguments (array of string, optional): Extra command-line arguments passed to the launched process (or activation arguments for packaged apps).
• aumid (string, optional): Explicit AUMID for a packaged app. Cleaner alternative to overloading bundle_id. Takes precedence over bundle_id / name when present.
• bundle_id (string, optional): App User Model ID (AUMID) for a packaged app — pattern {PackageFamilyName}!{ApplicationId}, e.g. Microsoft.WindowsNotepad_8wekyb3d8bbwe!App. Falls back to a name alias if no ! is present. Either bundle_id, name, aumid, path, or launch_path must be provided.
• creates_new_application_instance (boolean, optional): Accepted for parity; no-op on Windows (ShellExecuteEx always creates a new process).
• launch_path (string, optional): Round-trip the launch_path returned by list_apps. Highest precedence — when set, this exact string is handed to ShellExecuteEx unchanged. For Windows desktop apps it's the full .exe commandline (path + arguments preserved from the source shortcut); for UWP apps it's shell:appsFolder\{PackageFamilyName}!{AppId}. For precise UWP pid capture, prefer aumid over launch_path.
• name (string, optional): App display name. Tried against the shell:AppsFolder index first for packaged-app lookup; on a miss, passed to ShellExecuteEx's PATH search.
• path (string, optional): Full path to executable. Windows-only; takes precedence over name/bundle_id/aumid (but not over launch_path).
• start_minimized (boolean, optional): When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background — the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only screenshot and delivery_mode:"foreground" need it restored.
• urls (array of string, optional): URLs to open in the default browser via ShellExecuteEx (no activation).
• webkit_inspector_port (integer, optional): Accepted for cross-platform parity; no-op on Windows.

kill_app#

Force-terminate a process by pid. Use when the standard close path (Alt+F4 / WM_CLOSE via click on the X button) fails to make the process exit — typical for UWP / WinUI3 apps (Calculator, Photos, modern Notepad) that route WM_CLOSE into a suspended-but-resident state. Equivalent to taskkill /F /PID <pid>. Unsaved state is lost. Prefer the click-the-X path first; only escalate to kill_app when polite close didn't terminate.

Arguments:

• pid (integer, required): PID of the process to terminate.

{"pid":844}

bring_to_front#

Activate pid's window (or window_id if specified) -- bring it to the OS foreground.

This deliberately breaks the no-foreground contract. It is not part of the normal input ladder. For an ordinary background_unavailable response, retry only the refused action with delivery_mode:"foreground"; the input tool performs its own activate, act, and restore sequence. Use bring_to_front only for a focus-proxy surface that must remain foreground across multiple calls, such as an RDP or Windows App session, or when repeated action-scoped activation prevents the remote surface from accepting input.

Implementation uses the AttachThreadInput trick to bypass Windows' foreground-lock when the daemon is not at UIAccess integrity. Returns structured {previous_fg_hwnd, now_fg_hwnd} so callers can later restore. Windows only; macOS / Linux return an error pointing at platform-native alternatives.

Arguments:

• pid (integer, required): Target process ID.
• window_id (integer, optional): Optional HWND. Defaults to pid's first visible top-level window.

{"pid":844}

set_window_frame#

Set one exact top-level window's frame in the desktop-coordinate space reported by list_windows and verify the resulting geometry through an independent readback.

Arguments:

• height (number, required): range: 1–unbounded
• pid (integer, required): range: 1–unbounded
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• width (number, required): range: 1–unbounded
• window_id (integer, required): range: 1–unbounded
• x (number, required)
• y (number, required)

{"height":1,"pid":844,"width":1,"window_id":10725,"x":100,"y":200}

click#

Left-click against a target pid. Prefer element_index over pixel coordinates — element_index works on backgrounded / minimized / hidden / off-desktop windows, surfaces a stable handle that survives rebuilds, and tells you what you're clicking via the cached element's role + label. Reach for x, y only when the target is a canvas / video / WebGL / custom-drawn surface that doesn't appear in the UIA tree.

Two addressing modes:

• element_index + window_id (from the last get_window_state snapshot of that window) — performs the UIA Invoke pattern on the cached element via PostMessage. No cursor move, no focus steal. Requires a prior get_window_state(pid, window_id) in this turn; the element_index cache is scoped per (pid, window_id) and is replaced by the next snapshot of the same window.

• x, y (window-local screenshot pixels, top-left origin of the PNG returned by get_window_state). On delivery_mode:"background" (the default), cua-driver FIRST does a UIA hit-test at the resolved screen position: if the deepest invokable element under that point exposes InvokePattern, it's invoked through the accessibility channel — same background-safe path as the element_index mode, no foreground swap, no visible flash. This makes pixel clicks on UWP / WinUI3 / Win11 packaged apps work flash-free out of the box — agents should default to delivery_mode:"background" even on XAML hosts whose CoreInput dispatcher drops raw PostMessage. The PostMessage(WM_LBUTTONDOWN/UP) fallback only runs when the UIA hit-test misses (canvas / video / WebGL / custom-drawn surfaces with no UIA peer), and on those targets delivery_mode:"background" returns a structured background_unavailable error if PostMessage is known to drop too — at which point you switch to delivery_mode:"foreground". Always try the default background click first and let that error be your signal — do NOT pass foreground preemptively because the target 'looks like' GTK/Chromium/etc. The driver decides when background is impossible; a guessed foreground click needlessly steals the user's focus. count: 2 posts two down/up pairs for a double-click. Pixel clicks need a visible on-screen window to anchor the coordinate conversion (errors with pid X has no on-screen window otherwise).

Exactly one of element_index or (x AND y) must be provided. pid is required for window scope and omitted for desktop scope. window_id is required when element_index is used (scopes the cache lookup). After a zoom call, pass from_zoom=true to auto-translate zoom-image coords back to full-window space.

Windows-only convenience: button: "left"|"right"|"middle" switches the mouse button (Swift exposes right-click as a separate right_click tool). The Swift-only action / modifier / debug_image_out schema fields aren't supported yet.

Arguments:

• button (string, optional): Mouse button. Default "left".
• count (integer, optional): Click count — 1 (single), 2 (double), 3 (triple). Default 1. range: 1–3
• delivery_mode (string, optional): Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh — it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess — fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface.
• element_index (integer, optional): Element index from get_window_state. Requires the matching snapshot_id alongside it. Prefer element_token, which carries both values.
• element_token (string, optional): Opaque per-snapshot element handle from structuredContent.elements[].element_token. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.
• from_zoom (boolean, optional): When true, x and y are pixel coordinates in the last zoom image for this pid. The driver maps them back to window coords.
• modifier (array of string, optional): Modifier keys held during the action: cmd, shift, option/alt, ctrl.
• pid (integer, optional): Target process ID for window scope. Omit with scope=desktop for screen-absolute coordinates from get_desktop_state.
• scope (string, optional): default: "window"
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• snapshot_id (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.
• target (window target or desktop target, optional): Exact capture/input target selected independently for each action.

display_id="primary" is the portable desktop target in this release. Platforms that cannot address another display reject it explicitly rather than silently changing coordinate spaces.

• window_id (integer, optional): HWND for the window whose get_window_state produced the element_index. Required when element_index is used. Optional when element_token is supplied (the token carries it).
• x (number, optional): X in window-local screenshot pixels — same space as the PNG get_window_state returns. Must be provided together with y.
• y (number, optional): Y in window-local screenshot pixels. Must be provided together with x.

double_click#

Double-click against a target pid. Two addressing modes:

• element_index + window_id (from the last get_window_state snapshot of that window) — synthesizes a stamped pixel double-click at the element's cached on-screen center via PostMessage. (Windows has no AXOpen analogue; Swift's AXOpen-first path falls through to the same pixel recipe when the element doesn't advertise AXOpen, so the user-visible behavior matches.)

• x, y (window-local screenshot pixels, top-left origin of the PNG returned by get_window_state) — posts two WM_LBUTTONDOWN/UP pairs in quick succession to the deepest child window at that point.

Exactly one of element_index or (x AND y) must be provided. pid is required in both modes. window_id is required when element_index is used. The macOS-only modifier field is accepted for parity (no-op on Windows — PostMessage doesn't propagate modifier-key state).

Arguments:

• delivery_mode (string, optional): Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh — it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess — fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface.
• element_index (integer, optional): Element index from get_window_state. Requires the matching snapshot_id alongside it. Prefer element_token, which carries both values.
• element_token (string, optional): Opaque per-snapshot element handle from structuredContent.elements[].element_token. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.
• from_zoom (boolean, optional): After a zoom call, pass true to translate zoom-image coords back to window space.
• modifier (array of string, optional): Modifier keys held during the action: cmd, shift, option/alt, ctrl.
• pid (integer, required): Target process ID.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• snapshot_id (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.
• window_id (integer, optional): HWND for the target window. Required when element_index is used. Optional when element_token is supplied (the token carries it).
• x (number, optional): X in window-local screenshot pixels. Must be provided together with y.
• y (number, optional): Y in window-local screenshot pixels. Must be provided together with x.

{"pid":844}

right_click#

Right-click against a target pid. Two addressing modes:

• element_index + window_id (from the last get_window_state snapshot of that window) — posts WM_RBUTTONDOWN/UP at the element's cached on-screen center via PostMessage. (Windows has no AXShowMenu analogue wired up yet; Swift's AX-action path falls through to the same pixel recipe on non-advertising elements, so user-visible behavior matches.)

• x, y (window-local screenshot pixels, top-left origin of the PNG returned by get_window_state) — posts WM_RBUTTONDOWN/UP to the deepest child window at that point.

Exactly one of element_index or (x AND y) must be provided. pid is required in both modes. window_id is required when element_index is used. modifier is accepted for parity (no-op on Windows — PostMessage doesn't propagate modifier-key state).

Arguments:

• delivery_mode (string, optional): Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh — it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess — fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface.
• element_index (integer, optional): Element index from get_window_state. Requires the matching snapshot_id alongside it. Prefer element_token, which carries both values.
• element_token (string, optional): Opaque per-snapshot element handle from structuredContent.elements[].element_token. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.
• from_zoom (boolean, optional): After a zoom call, pass true to translate zoom-image coords back to window space.
• modifier (array of string, optional): Modifier keys held during the action: cmd, shift, option/alt, ctrl.
• pid (integer, required): Target process ID.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• snapshot_id (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.
• window_id (integer, optional): HWND for the target window. Required when element_index is used. Optional when element_token is supplied (the token carries it).
• x (number, optional): X in window-local screenshot pixels. Must be provided together with y.
• y (number, optional): Y in window-local screenshot pixels. Must be provided together with x.

{"pid":844}

drag#

Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. duration_ms (default 500) is the wall-clock budget; steps (default 20) interpolates intermediate WM_MOUSEMOVE events along the path. No focus steal. After a zoom call, pass from_zoom=true. Drags that start on a window caption / title bar or resize border (i.e. moving or resizing the window itself) cannot be delivered in the background — the OS move/resize loop needs real pointer input — so they return background_unavailable; re-issue those with delivery_mode:"foreground".

Arguments:

• button (string, optional): Mouse button. Default "left".
• delivery_mode (string, optional): Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh — it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess — fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface.
• duration_ms (integer, optional): Wall-clock duration of drag path. Default: 500. range: 0–10000
• from_x (number, required): Drag-start X in window-local screenshot pixels.
• from_y (number, required): Drag-start Y in window-local screenshot pixels.
• from_zoom (boolean, optional): When true, coordinates are in the last zoom image for this pid.
• modifier (array of string, optional): Modifier keys held during the action: cmd, shift, option/alt, ctrl.
• pid (integer, optional): Target process ID.
• scope (string, optional): Use desktop with no pid/window_id for screen-absolute coordinates.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• steps (integer, optional): Number of intermediate WM_MOUSEMOVE events. Default: 20. range: 1–200
• target (window target or desktop target, optional): Exact capture/input target selected independently for each action.

display_id="primary" is the portable desktop target in this release. Platforms that cannot address another display reject it explicitly rather than silently changing coordinate spaces.

• to_x (number, required): Drag-end X in window-local screenshot pixels.
• to_y (number, required): Drag-end Y in window-local screenshot pixels.
• window_id (integer, optional): Target window handle (HWND). Optional — driver picks frontmost window of pid when omitted.

{"from_x":100,"from_y":200,"to_x":100,"to_y":200}

type_text#

Insert text into the target pid via character-by-character PostMessage(WM_CHAR) to the focused window. No focus steal.

Special keys (Return, Escape, arrows, Tab) go through press_key / hotkey — they are not text.

Routing on Windows. When the target's owning EXE or top-level window class identifies it as a XAML / WinUI3 / UWP host (modern Notepad, Calculator, Photos, Settings, etc.), the tool requires element_index + window_id and routes through UI Automation's ValuePattern.SetValue — same backend as the set_value tool. PostMessage WM_CHAR doesn't reach those hosts (their CoreInput dispatcher only consumes events from the system input queue), so the fallback path silently dropped chars. If you call type_text(pid, text) on a XAML host without element_index, the tool returns an actionable error pointing you at get_window_state first. Native ConsoleHost on Windows ARM64 is hard-refused because it can accept synthesized Unicode events without delivering them; use a process or PTY setup channel instead. Legacy Win32 apps still use the PostMessage path, preserving the no-focus-steal property.

delay_ms (0–200, default 30) spaces successive characters on the PostMessage path so autocomplete and IME can keep up. Ignored on the UIA path (SetValue is atomic).

Arguments:

• delay_ms (integer, optional): Milliseconds between characters. Default 30. range: 0–200
• delivery_mode (string, optional): Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh — it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess — fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface.
• element_index (integer, optional): Element index from the last get_window_state for the same (pid, window_id). When supplied, type_text writes through UIA ValuePattern and reads that exact element back by handle. The shared ActionResult is confirmed only when the complete expected value is synchronously visible. If SetValue succeeds but read-back is stale or unavailable, the result is unverifiable with no escalation; take a fresh snapshot before retrying because deferred providers may publish only after this call returns. Requires window_id.
• element_token (string, optional): Opaque per-snapshot element handle from structuredContent.elements[].element_token. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.
• pid (integer, optional): Target process ID.
• scope (string, optional): Use desktop with no pid/window_id to type into the current foreground application.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• snapshot_id (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.
• target (window target or desktop target, optional): Exact capture/input target selected independently for each action.

display_id="primary" is the portable desktop target in this release. Platforms that cannot address another display reject it explicitly rather than silently changing coordinate spaces.

• text (string, required): Text to insert at the focused element's cursor.
• window_id (integer, optional): HWND of the target window. Required when element_index is used. Optional when element_token is supplied (the token carries it).
• x (number, optional): Window-local screenshot-pixel X of the field to type into — the element px action form. Pass x,y (no element_index) and the tool pixel-clicks there to establish real renderer focus, then types. Use for Chromium/Electron inputs the UIA/WM_CHAR path can't reach. Read straight off the get_window_state PNG, same convention as click.
• y (number, optional): Window-local screenshot-pixel Y of the field (see x).

{"text":"hello"}

press_key#

Press and release a single key, delivered directly to the target pid's top-level window via PostMessage(WM_KEYDOWN/WM_KEYUP). The target does NOT need to be frontmost — no focus steal.

Optional window_id selects a specific HWND when the pid owns more than one; without it the first visible top-level window for the pid is used.

Key vocabulary: return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, plus any letter or digit. Optional modifiers array takes ctrl/shift/alt/win. For true combinations (ctrl+c), hotkey is a cleaner surface.

element_index focuses the cached UIA element before sending the key; the top-level window remains backgrounded when delivery_mode is background.

Arguments:

• delivery_mode (string, optional): Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh — it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess — fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface.
• element_index (integer, optional): Optional element_index from the last get_window_state; focuses that UIA element before the key is delivered.
• element_token (string, optional): Opaque per-snapshot element handle from structuredContent.elements[].element_token. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.
• key (string, required): Key name (return, tab, escape, up, down, left, right, space, delete, home, end, pageup, pagedown, f1-f12, letter, digit).
• modifiers (array of string, optional): Optional modifier names held while the key is pressed (ctrl/shift/alt/win).
• pid (integer, optional): Target process ID.
• scope (string, optional): Use desktop with no pid/window_id to send the key to the current foreground application.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• snapshot_id (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.
• target (window target or desktop target, optional): Exact capture/input target selected independently for each action.

display_id="primary" is the portable desktop target in this release. Platforms that cannot address another display reject it explicitly rather than silently changing coordinate spaces.

• window_id (integer, optional): HWND for the target window. Required when element_index is used; otherwise auto-resolves the pid's first visible window.
• x (number, optional): Window-local screenshot-pixel X — the element px action form: pixel-click there to focus, then send the key. Use when the key must go to a Chromium/Electron surface the UIA path can't focus. Pass with y, no element_index.
• y (number, optional): Window-local screenshot-pixel Y (see x).

{"key":"return"}

hotkey#

Press a combination of keys simultaneously — e.g. ["ctrl", "c"] for Copy, ["ctrl", "shift", "t"] for reopen-closed-tab. Dispatch is target-aware:

• Modern XAML / WinUI / UWP targets route through UI Automation: the driver walks the target's accessibility subtree, finds a descendant whose AcceleratorKey matches the combo, and invokes it. No focus steal, no system-queue input.

• Legacy Win32 targets with modifiers (Ctrl+S, Alt+Tab, etc.) route through SendInput against the system input queue, with a brief SetForegroundWindow swap so the events land on the target. This path is necessary because PostMessage(WM_KEYDOWN, VK_CONTROL) does NOT update the OS-wide modifier state visible to GetKeyState / TranslateAccelerator, so Win32 apps that bind accelerators via TranslateAccelerator (LibreOffice, FAR, classic Notepad, etc.) never see the combo as a real accelerator on the PostMessage-only path. Trade-off: brief foreground swap (mitigated by restoring the previous foreground after the keystrokes flush). Requires the daemon to have UIAccess integrity so SetForegroundWindow is permitted — the MCP proxy auto-prefers the cua-driver-uia.exe worker pipe when both daemons are running.

• Legacy Win32 targets without modifiers (plain enter, tab, f5, etc.) route through PostMessage(WM_KEYDOWN/UP) — no focus steal, no need to update modifier state.

The target does NOT need to be frontmost in any branch.

window_id (optional): explicit HWND when the pid owns more than one window; otherwise the pid's first visible window is used.

Recognized modifiers: ctrl/control, shift, alt, win/windows. Non-modifier keys use the same vocabulary as press_key (return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, letters, digits). Order: modifiers first, one non-modifier last.

Arguments:

• delivery_mode (string, optional): Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh — it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess — fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface.
• element_index (integer, optional): Element index from get_window_state. Requires the matching snapshot_id alongside it. Prefer element_token, which carries both values.
• element_token (string, optional): Opaque per-snapshot element handle from structuredContent.elements[].element_token. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.
• keys (array of string, required): Modifier(s) and one non-modifier key, e.g. ["ctrl", "c"]. items: 2–unbounded
• pid (integer, optional): Target process ID.
• scope (string, optional): Use desktop with no pid/window_id to send the hotkey to the current foreground application.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• snapshot_id (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.
• target (window target or desktop target, optional): Exact capture/input target selected independently for each action.

display_id="primary" is the portable desktop target in this release. Platforms that cannot address another display reject it explicitly rather than silently changing coordinate spaces.

• window_id (integer, optional): Explicit HWND when the pid owns multiple windows.
• x (number, optional): Window-local screenshot-pixel X — the element px action form: pixel-click there to focus, then send the combo (so e.g. Ctrl+V pastes into that field). Pass with y. Use for Chromium/Electron surfaces the background combo can't reach.
• y (number, optional): Window-local screenshot-pixel Y (see x).

{"keys":["cmd","c"]}

set_value#

Set a value on a UIA element via the ValuePattern interface.

Two semantic modes (matching Swift's split):

• Standard input (text fields, sliders, combo box edit): writes the value directly through UIA IUIAutomationValuePattern::SetValue. This is the canonical Windows write path, equivalent to Swift's AXValue write.
• ComboBox / select dropdown: ValuePattern.SetValue picks the option whose text matches value on most native ComboBox controls.

For free-form text entry that the target accepts via keystrokes only, prefer type_text — UIA ValuePattern writes are ignored by some web inputs (same caveat as Swift's AXValue-vs-WebKit).

Arguments:

• element_index (integer, optional): Element index from get_window_state. Requires the matching snapshot_id alongside it. Prefer element_token, which carries both values.
• element_token (string, optional): Opaque per-snapshot element handle from structuredContent.elements[].element_token. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.
• pid (integer, required): Target process ID.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• snapshot_id (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.
• value (string, required): New value. UIA will coerce to the element's native type.
• window_id (integer, optional): HWND of the window. Required when element_index is used; optional when element_token is supplied (the token carries it).

{"pid":844,"value":"42"}

scroll#

Scroll the target pid's focused region.

Windows transport: WM_VSCROLL / WM_HSCROLL posted to the window — the same events the OS sends when scrollbars or trackpads scroll, so any window that handles scrollbars correctly responds to this. Swift uses synthesized keystrokes (PageDown / arrow keys) via auth-signed SLEventPostToPid; both approaches reach backgrounded windows.

Mapping: by: "page" → SB_PAGEDOWN/UP/LEFT/RIGHT × amount; by: "line" → SB_LINEDOWN/UP/LEFT/RIGHT × amount.

Note: element_index is accepted for cross-platform parity but currently no-op on Windows (UIA SetFocus not wired up yet — same caveat as press_key).

Arguments:

• amount (integer, optional): Number of scroll ticks. Default 3. range: 1–50
• by (string, optional): Scroll granularity. Default: line.
• delivery_mode (string, optional): Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh — it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess — fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface.
• direction (string, required)
• element_index (integer, optional): Optional element_index. Accepted for parity; currently no-op on Windows.
• element_token (string, optional): Opaque per-snapshot element handle from structuredContent.elements[].element_token. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.
• pid (integer, optional): Target process ID for window scope. Omit with scope=desktop for screen-absolute coordinates from get_desktop_state.
• scope (string, optional): default: "window"
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• snapshot_id (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.
• target (window target or desktop target, optional): Exact capture/input target selected independently for each action.

display_id="primary" is the portable desktop target in this release. Platforms that cannot address another display reject it explicitly rather than silently changing coordinate spaces.

• window_id (integer, optional): HWND of the target window. Required when element_index is used; otherwise auto-resolves the pid's first visible window.
• x (number, optional): With pid/window_id: window-local screenshot X used to target a nested scroll surface in foreground mode. Without pid/window_id: screen-absolute X for desktop scope. Must be paired with y.
• y (number, optional): With pid/window_id: window-local screenshot Y used to target a nested scroll surface in foreground mode. Without pid/window_id: screen-absolute Y for desktop scope. Must be paired with x.

{"direction":"up"}

move_cursor#

Move the agent cursor overlay to (x, y). Does NOT move the real mouse cursor.

Arguments:

• cursor_id (string, optional)
• scope (string, optional): desktop moves the real OS pointer; window moves only the agent overlay.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• target (window target or desktop target, optional): Preferred per-call target. New callers should set this field.
• x (number, required)
• y (number, required)

{"x":100,"y":200}

zoom#

Zoom into a rectangular region of a window screenshot at full (native) resolution. Use this when get_window_state returned a resized image and you need to read small text, identify icons, or verify UI details.

Coordinates x1, y1, x2, y2 are in the same pixel space as the screenshot returned by get_window_state (i.e. the resized image if max_image_dimension is active). The maximum zoom region width is 500 px in scaled-image coordinates.

A 20% padding is automatically added on every side of the requested region so the target remains visible even if the caller's coordinates are slightly off.

After a zoom, pass from_zoom=true to click/type_text to auto-translate coordinates back to full-window space.

Windows-specific: window_id is the canonical addressing field (HWND). pid is also required (used to scope the zoom translation registry, matching Swift's per-pid zoom context).

Arguments:

• pid (integer, optional): Target process ID. Validated in code (an explicit "Missing required integer field pid" error when absent); kept out of required to match the shared cross-platform zoom contract.
• window_id (integer, required): HWND of the target window.
• x1 (number, required): Left edge of the region (resized-image pixels).
• x2 (number, required): Right edge of the region (resized-image pixels).
• y1 (number, required): Top edge of the region (resized-image pixels).
• y2 (number, required): Bottom edge of the region (resized-image pixels).

{"window_id":10725,"x1":100,"x2":100,"y1":200,"y2":200}

Browser tools#

page#

Legacy browser compatibility tool. Prefer get_browser_state and the typed browser_* tools for exact targeting, endpoint ownership, and consent. Read-only get_text and query_dom remain available by default. Mutating actions require the daemon operator to set CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS=1 before daemon startup (restart the daemon after changing it); this escape hatch does not provide the typed browser surface's exact binding or existing-profile grant guarantees. Supports Chrome, Brave, Edge, Safari (via AppleScript on macOS), Electron apps (via CDP), Chromium/Firefox on Windows (via UIA for read; CDP for execute_javascript when --remote-debugging-port is set), and WKWebView/Tauri/AT-SPI fallbacks.

Actions:

• execute_javascript: Run JS and return the result.
• get_text: Extract visible text from the page.
• query_dom: Find elements matching a CSS selector.
• click_element: Click a CSS-selected element AND animate the agent cursor to its on-screen center first (so the user sees what the agent is doing). Prefer over execute_javascript('el.click()') whenever you want visible cursor feedback.
• insert_text: Insert text at whatever currently holds DOM focus in one native operation (CDP Input.insertText) — no synthesized key events, but more durable than a one-shot execute_javascript write since rich-text editors already have to treat it like an IME commit. Try this before type_keystrokes on a contenteditable that discarded an execute_javascript write. Click/focus the target field first.
• type_keystrokes: Type text via real per-character keystroke events into whatever currently holds DOM focus. Slower than insert_text but the most durable rung — use it when insert_text also gets discarded, or the editor's own keydown/keyup handlers need to see real keys. Click/focus the target field first.
• enable_javascript_apple_events: macOS-only — patch the browser's Preferences to allow JS from Apple Events (Chrome/Brave/Edge, requires user confirmation and a browser restart).

Arguments:

• action (string, required): Action to perform.
• attributes (array of string, optional): Element attributes to include in query_dom results.
• bundle_id (string, optional): Bundle ID of the browser. Required for enable_javascript_apple_events (macOS only).
• cdp_port (integer, optional): Optional, for execute_javascript/insert_text/type_keystrokes: use this exact CDP port instead of auto-discovering one from pid. Needed when the port was opened via the browser's own remote-debugging toggle rather than a launch-time flag, since that path may not answer the auto-discovery probe. range: 1–65535
• css_selector (string, optional): CSS selector for query_dom (e.g. 'a', 'button', 'input', 'h1'-'h6', 'p', 'img', 'select', '*').
• javascript (string, optional): JavaScript to execute. Required for execute_javascript.
• pid (integer, optional): Target process ID.
• selector (string, optional): CSS selector for click_element (e.g. 'button.submit', '#login a').
• target_url_contains (string, optional): Optional, for execute_javascript/insert_text/type_keystrokes: require exactly one browser tab whose URL contains this substring. Use this on a multi-tab browser — there's no built-in link between window_id and which tab a CDP call reaches.
• text (string, optional): Text to insert or type. Required for insert_text and type_keystrokes. The target field must already have DOM focus (click/focus it first).
• user_has_confirmed_enabling (boolean, optional): Must be true to proceed with enable_javascript_apple_events. This will quit and relaunch the browser.
• window_id (integer, optional): Target window ID from list_windows.

{"action":"execute_javascript"}

Clipboard tools#

clipboard_read#

List available system clipboard types and optionally return privacy-sensitive plain text. Clipboard content is never retained in telemetry.

Arguments:

• include_text (boolean, optional): Return plain-text clipboard content in addition to the available types. Clipboard content is privacy-sensitive and is never retained in telemetry. default: false
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.

clipboard_write#

Replace the system clipboard with exactly one value: plain text, an image from an absolute local path, or a file URL from an absolute local path. Returns the available types for read-back before paste.

Arguments:

• file_path (string, optional): Absolute path to a local file to place on the clipboard as a file URL.
• image_path (string, optional): Absolute path to a local image to place on the clipboard.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• text (string, optional): Plain text to place on the clipboard.

Recording tools#

start_recording#

Start trajectory recording. Every subsequent action-tool invocation (click, right_click, scroll, type_text, press_key, hotkey, set_value) writes a turn folder under output_dir:

• before_state.json / after_state.json — application AX/UIA/AT-SPI state immediately before and after the action.
• before.png / after.png — target-window screenshots immediately before and after the action.
• evidence.json — capture status and a stable classification when an expected artifact could not be captured.
• app_state.json — post-action AX/UIA snapshot for the target pid.
• screenshot.png — compatibility alias of after.png.
• action.json — tool name, full input arguments, result summary, result-error flag, pid, click point (when applicable), ISO-8601 timestamp.
• click.png — for dispatched click-family actions only, before.png with a red marker at the click point. A call refused before target resolution is explicitly not applicable instead.

Turn folders are named turn-00001/, turn-00002/, etc. Turn numbering restarts at 1 each time recording is (re-)started.

Video is off by default. Pass record_video: true to also capture the main display to <output_dir>/recording.mp4 (H.264 / 30 fps) for the lifetime of the session. The recording is torn down automatically when the MCP client disconnects.

macOS uses native ScreenCaptureKit (daemon-owned SCStream + SCRecordingOutput) so video inherits the daemon's Screen Recording grant — no extra TCC prompt, no ffmpeg subprocess. Requires macOS 15.0+.

Windows + Linux use an ffmpeg subprocess (gdigrab / x11grab + libx264). Requires ffmpeg on PATH (winget install Gyan.FFmpeg / apt install ffmpeg); when ffmpeg is missing or fails on startup the per-turn capture (screenshots + action.json) still runs and the session's last_error field carries the diagnostic.

State persists for the life of the daemon; a restart resets to disabled with no on-disk state. Call stop_recording to disable + finalize the mp4.

Arguments:

• output_dir (string, required): Absolute or ~-rooted directory where turn folders and (when enabled) the video file are written.
• record_video (boolean, optional): Capture the main display to <output_dir>/recording.mp4. Default: false. Set to true to also capture the main display to recording.mp4 (otherwise only the per-turn screenshots + JSON are recorded). On macOS this uses native ScreenCaptureKit (no extra TCC prompt, macOS 15.0+); on Windows + Linux it requires ffmpeg on PATH.

{"output_dir":"~/cua-trajectories/demo1"}

stop_recording#

Stop trajectory recording. Disables further per-turn capture and, when video was enabled, gracefully terminates the ffmpeg subprocess so the mp4's moov atom is finalized (the file is playable). Calling stop on an already-stopped session is a no-op. The response carries last_video_path pointing at the finalized mp4 (when video was on).

A manual stop_recording is unconditional — it stops whatever recording is active regardless of which session started it. Ownership-scoped teardown (so one client disconnecting can't stop a recording a later client started) is handled by the registry's session_end lifecycle hook, not by this tool.

Arguments: none.

replay_trajectory#

Replay a recorded trajectory by re-invoking every turn's tool call in lexical order. dir must point at a directory previously written by start_recording. Each turn-NNNNN/ is parsed for action.json, and the recorded tool is called with its recorded arguments via the same dispatch path an MCP / CLI call uses.

Caveats:

• Element-indexed actions (click({pid, element_index}) etc.) will fail because element indices are per-snapshot and don't survive across sessions. Pixel clicks (click({pid, x, y})) and all keyboard tools replay cleanly. Failures are reported but don't stop replay unless stop_on_error is true.
• get_window_state and other read-only tools are NOT currently recorded, so replays do not re-populate the per-(pid, window_id) element cache.
• If recording is ENABLED while replay runs, the replay itself is recorded into the currently configured output directory. That's deliberate: recording a replay against a new build and diffing the two trajectories is the regression-test workflow.

Arguments:

• delay_ms (integer, optional): Milliseconds to sleep between turns, for human-observable pacing. Default 500. range: 0–10000
• dir (string, required): Trajectory directory previously written by start_recording. Absolute or ~-rooted.
• stop_on_error (boolean, optional): Stop replay on the first tool-call error. Default true — set false to best-effort through the full trajectory.

{"dir":"~/cua-trajectories/demo1"}

Configuration tools#

set_config#

Write a setting into the persistent driver config. Values take effect immediately.

Two input shapes:

• Swift-compatible (preferred): {"key": "max_image_dimension", "value": 1568} — single dotted-path leaf write.
• Legacy per-field (Rust-only): {"max_image_dimension": 0} — bulk write of named fields.

Known keys:

• capture_mode (string: vision | ax | som) — DEPRECATED and ignored; get_window_state always returns both the UIA tree and a screenshot. Still accepted/persisted for back-compat but has no effect.
• max_image_dimension (integer)
• experimental_pip (boolean; persisted to config.json, applies on next daemon restart — Windows backend stubbed today, see issue #1729)
• experimental_pip_geometry (string WxH or WxH+X+Y; persisted; applies on next daemon restart)

Returns the full updated config in the same shape as get_config.

Arguments:

• capture_mode (string, optional): DEPRECATED and ignored — get_window_state always returns both the UIA tree and a screenshot. Still accepted/persisted for back-compat but has no effect. ("som"/"screenshot" still decode as deprecated aliases.)
• experimental_pip (boolean, optional): Legacy per-field shape. Enables PiP preview (applies next restart).
• experimental_pip_geometry (string, optional): Legacy per-field shape. PiP window size + optional position.
• key (string, optional): Dotted snake_case path to a leaf config field (Swift-compatible shape). Pair with value.
• max_image_dimension (integer, optional): Legacy per-field shape.
• value (unknown, optional): New value for key. JSON type depends on the key.

start_session#

Optionally create or return a lifecycle session before acting. For multi-call work, prefer a short public session label and repeat it on every call that accepts it; an omitted value uses the authenticated transport lease's implicit session instead. This tool is optional because an ordinary action can create or reuse a named run directly. Use it to set the initial cursor theme before acting or to revive a public name after it has ended; ordinary actions never revive ended names. capture_scope is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.

Arguments:

• capture_scope (string, optional): Deprecated compatibility policy. New callers select window or desktop modality on each action instead of storing it on the session.
• cursor_theme (object or null, optional): Optional initial cursor theme. The host applies it before the cursor is first made visible, avoiding a flash of the default theme.
• session (string, optional): Optional stable public label for this run (e.g. "research-run-1"). When omitted, the authenticated transport lease's implicit session is created or returned.

end_session#

End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. Omit session to end the authenticated transport's implicit session. Idempotent.

Arguments:

• session (string, optional): Optional public label to end. When omitted, end the caller's attached implicit session.

set_agent_cursor_enabled#

Show or hide the agent cursor owned by a session.

Arguments:

• enabled (boolean, required)
• session (string, required)

{"enabled":false,"session":"example"}

set_agent_cursor_motion#

Configure only movement physics and visibility timing for a session cursor.

Arguments:

• arc_flow (number or null, optional)
• arc_size (number or null, optional)
• dwell_after_click_ms (number or null, optional)
• end_handle (number or null, optional)
• glide_duration_ms (number or null, optional)
• idle_hide_ms (number or null, optional)
• session (string, required)
• spring (number or null, optional)
• start_handle (number or null, optional)
• turn_radius (number or null, optional)

{"session":"example"}

Maintenance tools#

check_permissions#

Check required permissions for cua-driver-rs on Windows.

Arguments: none.

health_report#

Single-call end-to-end driver diagnostics. Designed to let downstream consumers ship one stable call instead of stitching together check_permissions, doctor, version, bundle attribution, and platform capability status. On macOS, prompt-capable direct capture is deliberately skipped; use cua-driver permissions grant to verify it explicitly. cua-driver owns the health model; consumers stay thin.

Input — all optional: { "include": ["<check_name>", ...], // run only these "skip": ["<check_name>", ...] // skip these } If both are given, include wins.

Canonical check names: macOS : binary_version, platform_supported, session_active, bundle_identity, tcc_accessibility, tcc_screen_recording, ax_capability, screen_capture_capability Windows: binary_version, platform_supported, session_active, ax_capability (via UIA), screen_capture_capability (via DXGI) Linux : binary_version, platform_supported, session_active, ax_capability (via AT-SPI), screen_capture_capability (via X11)

Output — stable contract, schema_version="1": { "schema_version": "1", "platform": "darwin" | "win32" | "linux", "driver_version": "<semver>", "overall": "ok" | "degraded" | "failed", "checks": [ { "name": "<one of the canonical names above>", "status": "pass" | "fail" | "skip", "message": "<one-line summary, always present>", "hint": "<remediation step, present when status=fail>", "data": { /* check-specific structured fields */ } }, ... ] }

overall rules:

• ok — every non-skipped check passes
• degraded — at least one non-core check fails (binary is still usable)
• failed — any core check fails (binary_version, platform_supported, session_active)

Stability: schema_version="1" is the contract. Future breaking changes will be "2". Adding new check names under the same schema_version is non-breaking; consumers must tolerate unknown check names.

Arguments:

• include (array of string, optional): Only run these checks (canonical names). Wins over skip.
• skip (array of string, optional): Skip these checks (canonical names). Ignored when include is set.

check_for_update#

Check the saved stable/nightly Cua Driver channel for a release on GitHub. Returns current and selected channels, current and latest versions, an update_available boolean, the install one-liner, and the release notes URL. Read-only — never installs. Mirror of cua-driver check-update --json.

Arguments: none.

install_ffmpeg#

Install the ffmpeg binary used by start_recording's video capture (Linux/Windows; macOS records natively and needs no ffmpeg). Two-step and confirmed: called without confirm it only REPORTS the exact install command for this platform's package manager; pass confirm: true to actually run it. No-op if ffmpeg is already on PATH. ffmpeg is run as a separate process, never linked into the driver.

Arguments:

• confirm (boolean, optional): Run the install command. Without it, only the planned command is reported.

Other tools#

verify_state#

Deterministically verify bounded predicates against one exact window. The driver evaluates structured window/accessibility state and may return the final screenshot as uninterpreted visual evidence for a multimodal caller. Predicate results are satisfied, unsatisfied, or unknown; unknown never implies success. Accessibility projections are conservative: absence remains unknown unless the observed search domain is proven exhaustive.

Arguments:

• expect (array of object, required): One to eight predicates, combined with logical AND. items: 1–8
• include_screenshot (boolean or null, optional): Return the final window screenshot as image content for a multimodal caller. The driver does not interpret that image.
• pid (integer, required): Exact process whose window may be observed. range: 1–unbounded
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. This field never selects capture modality or authorization.
• stable_samples (integer, optional): Consecutive satisfied samples required before returning success. default: 2; range: 1–5
• timeout_ms (integer, optional): Bounded wait. Zero performs one sample. default: 5000; range: 0–10000
• window_id (integer, required): Exact native window identifier.

{"expect":[{"window":{"exists":true}}],"pid":844,"window_id":10725}

invoke_menu#

Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels.

Arguments:

• path (array of string, required): items: 1–16
• pid (integer, required): range: 1–unbounded
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.
• window_id (integer, required): range: 1–unbounded

{"path":["example"],"pid":844,"window_id":10725}

debug_window_info#

Diagnostic: dump everything cua-driver sees about a pid's top-level windows from the daemon's session perspective. Returns window class names, owning .exe basename + path, and — when CUIAutomation succeeds — the focused UIA element with the list of patterns it supports (ValuePattern, InvokePattern, TextPattern, TogglePattern, etc.). Used to design / debug input routing for XAML / UWP / WinUI3 targets; see CUA-543.

Arguments:

• pid (integer, required): PID of the process to inspect.

{"pid":844}

set_agent_cursor_theme#

Select an already-installed cursor theme for a session.

Arguments:

• reduced_motion (string, optional): default: "auto"
• session (string, required)
• theme_id (string, required)

{"session":"example","theme_id":"example"}

get_browser_state#

Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup — a missing endpoint is a structured browser_requires_setup refusal pointing at browser_prepare.

Arguments:

• continuation (string, optional): Opaque continuation minted by an earlier semantic_v2 response.
• include_screenshot (boolean, optional): Capture the exact tab viewport as PNG through CDP without selecting the tab or foregrounding its native window. The request refuses if capture cannot be completed. default: false
• pid (integer, optional): Native browser process id (bind mode).
• query (string, optional): Read-only semantic match over role, accessible name, and visible text.
• scope_ref (string, optional): Current semantic/content ref whose subtree should be observed.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session.
• snapshot_format (string, optional): Versioned snapshot contract. dom_refs_v1 remains the compatibility default.
• tab_id (string, optional): Opaque tab id from get_browser_state (session-scoped).
• target_id (string, optional): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).
• window_id (integer, optional): Native window id owned by pid (bind mode).

browser_prepare#

Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused.

Arguments:

• allow_launch (boolean, optional): Allow a separate driver-owned isolated Chromium process to be launched (default false).
• pid (integer, optional): Browser process id to prepare. Required except for a driver-owned isolated_new/isolated_named launch with allow_launch=true.
• profile (object, optional)
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session.
• strategy (object, optional)
• window_id (integer, optional): Exact native window approval anchor; required for strategy.kind=existing_profile.

browser_navigate#

Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). Refused for heuristic bindings. Navigation invalidates all p<snapshot>:<index> refs for the tab.

Arguments:

• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session.
• tab_id (string, required): Opaque tab id from get_browser_state (session-scoped).
• target_id (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).
• url (string, required): Destination URL (http:, https:, or about:).

{"tab_id":"example","target_id":"example","url":"example"}

browser_click#

Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture. input_route="dom_event" (synthetic el.click(), ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.

Arguments:

• input_route (string, optional): "trusted" (default): Input.dispatchMouseEvent. It refuses rather than foregrounding a standalone browser. "dom_event": synthetic full-background DOM click, only when explicitly requested. Dispatch does not prove the control activated; refresh page state and verify the expected postcondition.
• ref (string, optional): Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session.
• tab_id (string, required): Opaque tab id from get_browser_state (session-scoped).
• target_id (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).
• x (number, optional): Viewport x (CSS px) — alternative to ref.
• y (number, optional): Viewport y (CSS px) — alternative to ref.

{"tab_id":"example","target_id":"example"}

browser_type#

Type text into an exactly-bound tab via the Input domain. mode="insert_text" (default) uses Input.insertText; mode="keystrokes" dispatches per-character key events. Both insert at the caret, so typing into a field that already holds text appends to it; pass replace=true to set the field instead, or to clear it by typing an empty string. Pass a ref to an editable element from the latest snapshot. A ref is required; heuristic bindings are refused.

Arguments:

• mode (string, optional): insert_text (default): bulk Input.insertText. keystrokes: per-character Input.dispatchKeyEvent.
• ref (string, required): Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab.
• replace (boolean, optional): false (default): insert at the caret, appending to whatever the field already holds. true: select the element's whole content first so the text replaces it — with an empty text this clears the field. Replacement goes through the selection, so beforeinput/input still fire and framework state stays consistent.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session.
• tab_id (string, required): Opaque tab id from get_browser_state (session-scoped).
• target_id (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).
• text (string, required): Text to type.

{"ref":"example","tab_id":"example","target_id":"example","text":"hello"}

browser_dialog#

Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. This never handles browser permission UI, extension UI, native dialogs, or file pickers. Inspect returns an opaque dialog_id; accept/dismiss require that exact current id. Resolution defaults to background delivery; Linux callers must explicitly request foreground delivery because Chromium's native modal cannot be resolved there without changing foreground posture.

Arguments:

• action (string, required)
• delivery_mode (string, optional): Requested foreground posture for accept/dismiss. Linux Chromium requires foreground; inspect is read-only. default: "background"
• dialog_id (string, optional): Opaque current dialog generation returned by action=inspect.
• prompt_text (string, optional): Sensitive response text, valid only when accepting a prompt dialog.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session.
• tab_id (string, required): Opaque tab id from get_browser_state (session-scoped).
• target_id (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).

{"action":"inspect","tab_id":"example","target_id":"example"}

browser_set_input_files#

Assign one or more explicit absolute local files to an exact live <input type=file> ref through CDP. This bypasses native file pickers, rejects symlinks and non-regular files, and never returns local paths.

Arguments:

• files (array of string, required): items: 1–32
• ref (string, required): Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab.
• session (string, optional): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session.
• tab_id (string, required): Opaque tab id from get_browser_state (session-scoped).
• target_id (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).

{"files":["example"],"ref":"example","tab_id":"example","target_id":"example"}

browser_download#

Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. Requires MCP-host destructive-tool approval, refuses ambiguous or stale capabilities, and never returns the source URL, filename, or destination path.

Arguments:

• destination_root (string, required): Absolute, existing, canonical directory approved to receive the download.
• ref (string, required): Live page ref whose activation initiates the download.
• session (string, required): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs.
• tab_id (string, required): Opaque exact tab id from get_browser_state.
• target_id (string, required): Opaque exact browser target id from get_browser_state.

{"destination_root":"example","ref":"example","session":"example","tab_id":"example","target_id":"example"}

browser_pointer#

Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. Semantic refs must declare pointer for hover, right-click, double-click, and drag; scroll accepts a scroll or pointer capability. The trusted route uses CDP Input events and refuses if standalone background posture cannot be preserved. The explicit dom_event route requires a page ref and synthesizes full-background DOM events. Never activates or brings a tab to the foreground.

Arguments:

• action (string, required)
• delta_x (number, optional): Horizontal scroll delta in CSS pixels.
• delta_y (number, optional): Vertical scroll delta in CSS pixels.
• destination_ref (string, optional): Drag destination page ref in the exact same frame.
• input_route (string, optional): default: "trusted"
• ref (string, optional): Origin page ref. Alternative to x/y.
• session (string, required): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs.
• tab_id (string, required): Opaque tab id minted by get_browser_state.
• target_id (string, required): Opaque target id minted by get_browser_state.
• to_x (number, optional): Drag destination viewport x in CSS pixels.
• to_y (number, optional): Drag destination viewport y in CSS pixels.
• x (number, optional): Origin viewport x in CSS pixels.
• y (number, optional): Origin viewport y in CSS pixels.

{"action":"hover","session":"example","tab_id":"example","target_id":"example"}

escalate_session#

Deprecated compatibility tool for legacy capture-scope sessions. New callers select window or desktop modality on each action. No deescalate_session tool exists.

Arguments:

• detail (string, optional): Optional bounded diagnostic detail. Never use secrets or page content.
• reason (string, required)
• session (string, required)

{"reason":"ax_tree_pixel_mismatch","session":"example"}

get_session#

Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. Omit session to inspect its implicit session.

Arguments:

• session (string, optional): Optional public label. When omitted, inspect the caller's attached implicit session.

list_sessions#

List content-free lifecycle summaries attached to this authenticated transport lease. It does not enumerate other callers' sessions.

Arguments:

• cursor (string, optional): Opaque continuation cursor returned by a previous call.
• limit (integer or null, optional): Maximum number of content-free summaries to return (default 50, max 100). Ordinary agent transports are scoped to their own lease. range: 0–unbounded

get_session_state#

Deprecated compatibility alias that reads a live legacy session's capture policy. Use get_session for lifecycle state.

Arguments:

• session (string, optional): Optional public label. When omitted, inspect the caller's attached implicit session.