| appsA | List applications with accessible UI elements. Returns application names visible in the accessibility tree.
Use these names to scope other tools (find, elements, screenshot). |
| diagnosticsA | Report backend, input, CDP, and optional dependency health. Args:
probe: If true (default), initialise optional providers and perform
discovery. Pass false for a side-effect-free state snapshot.
|
| windowsA | List all open windows. Returns window IDs, titles, sizes, and app names.
Use window IDs to scope find/elements queries or activate_window.
|
| findA | Search for UI elements by name — buttons, links, labels, fields. Matches against element names (button labels, link text, field
labels), NOT body text or prose content inside articles or
documents.
Returns element IDs that you can use with click, set_value, etc.
Use the FULL visible text for best results (e.g. "Send Message"
not just "Send").
Args:
query: Text to search for (e.g. "Send Message", "Submit", "Search").
app: Scope to this application (e.g. "Firefox", "Slack").
window_id: Scope to this window.
role: Only match this role (e.g. "button", "text_field", "link").
states: Only match elements with ALL these states (e.g. ["enabled", "visible"]).
max_results: Maximum matches to return.
fields: Which fields to search -- ["name"], ["name", "value"], or ["name", "value", "description"].
source: "full" (default, merged native+web), "cdp_ax" (CDP accessibility tree only), "native" (platform only), or "dom" (live DOM). "ax" remains as a compatibility alias for "cdp_ax".
|
| get_elementA | Get a single element by its ID with full detail. Returns a fresh snapshot with current states, value, supported
actions, and description. Use this to inspect an element
before calling the ``action()`` tool — the actions list shows
exactly which raw action names are available.
Args:
element_id: The element ID (from find/elements results).
|
| snapshotA | Return a tree-structured view of a window's UI. The primary orient tool in no-vision mode. In vision mode, use it
as a structural complement to screenshot() — cheaper than a
screenshot and gives element IDs directly. Default behaviour: pick
the currently active window, walk its accessibility tree, prune
anonymous structural wrappers, preserve semantic containers (dialogs,
menus, lists, etc.), and emit an indented text view with one line per
interactive element.
Args:
app: Snapshot the given app's active window (or first window).
Case-insensitive.
window_id: Snapshot a specific window by ID.
element_id: Start the tree walk from a specific element instead
of the window root. Use to dig into a container whose
children were not visible in a previous (truncated) snapshot.
To read the text content of a container, use read_text()
rather than snapshot().
all_elements: If true, include every named element — not just
interactive + container roles. Use when the default
filter is hiding something.
max_depth: Maximum tree depth to walk. Defaults to the
configured value (typically 20). Decrease for a faster
overview of a large window.
|
| screenshotA | Capture the screen and return an image. With no arguments, captures the full desktop. Specify one
parameter to crop to a specific target.
Args:
app: Crop to this application's window.
window_id: Crop to this specific window.
element_id: Crop to this element's bounding box.
padding: Extra pixels around the crop region.
monitor: Capture only this monitor (0-indexed).
|
| clickA | Click an element by ID, or at screen coordinates. Pass ``element_id`` to click via the element's native
accessibility action (most reliable). Pass ``x`` and ``y``
to click directly at screen coordinates instead — useful
when clicking by ID triggers an unintended action (e.g.
opens a dropdown instead of focusing a text entry).
Every element shows its position as @(x,y) in listings.
Coordinate clicks always report OK even if nothing was hit —
verify the result with a screenshot or find().
Args:
element_id: The element ID to click.
x: Screen X coordinate (use with y instead of element_id).
y: Screen Y coordinate (use with x instead of element_id).
button: "left" (default) or "right".
double_click: If true, perform a double-click instead.
Cannot be combined with button="right".
|
| set_valueA | Set the value of an editable element. Calls the platform's native value-setting API. Behaviour depends
on the target widget:
* Text fields / text areas: writes the text.
* Combo boxes / dropdowns / <select>: picks the option whose
label or value matches *value*. Prefer this over clicking
the dropdown and then clicking a popup item — picking by name
is one atomic call and avoids popup-click failures on some
toolkits.
* Other editable widgets: whatever their value interface accepts.
Args:
element_id: The element ID (a text field, combo box, etc.).
value: The text or option label to set.
replace: If true, clear the field first and replace all content.
If false (default), insert at the current cursor position.
|
| set_numeric_valueA | Set the numeric value of a range element (slider, spinbox). Args:
element_id: The element ID (a slider, spin button, etc.).
value: The numeric value to set.
|
| focusB | Move keyboard focus to an element. Args:
element_id: The element ID to focus.
|
| select_textA | Select a substring within an element's text content. Finds the text within the element and applies a native text
selection over that range. Works on editable fields and document
bodies on all backends. On web content (CDP) and Windows (UIA)
also works on read-only containers such as articles and sections.
Useful for formatting, copying, or replacing specific text.
Args:
element_id: The element ID containing the text.
text: The exact substring to select.
occurrence: Which occurrence to select (1 = first, 2 = second, etc.).
|
| actionA | Perform a raw accessibility action by exact name. Only call this when the element shows actions=[...] in snapshot()
output AND click() either failed silently or is not the right verb.
Use the exact action name shown in the snapshot — do not guess.
Example: an element showing actions=[expand, collapse] can be acted
on with action(element_id, "expand").
Args:
element_id: The element ID.
action_name: Exact action name from the snapshot actions=[...] list.
|
| read_textA | Return text content exposed by an element or container. Some backends expose aggregate descendant text for containers.
Pass a container ID from snapshot() to read an entire section,
article, dialog, or document body when the backend supports it.
Workflow: snapshot() to find the right container, read_text(id)
to read its full contents.
Args:
element_id: The element or container ID to read text from.
|
| type_textA | Type text into the currently focused element. Simulates keyboard input. Focus a text field first with
click() or focus(), then type into it.
Special characters:
\n = Enter (line break), \t = Tab (next field),
\b = Backspace (delete previous character).
Args:
text: The text to type.
raw: If true, type literal backslashes without converting
``\n``, ``\t``, or ``\b`` escape sequences.
|
| press_keyA | Press a key or key combination. Single key: "enter", "tab", "escape", "f5", "backspace".
Combination: ["ctrl", "s"], ["ctrl", "shift", "p"], ["alt", "f4"].
Args:
keys: A single key name, or a list of keys for a combination
(all held together, then released in reverse order).
repeat: Number of times to press (default 1).
|
| mouse_moveA | Move the mouse cursor to an element or to screen coordinates. Use this before scroll() to scroll within a specific area.
Args:
element_id: The element ID to move the cursor to.
x: Screen X coordinate (use with y instead of element_id).
y: Screen Y coordinate (use with x instead of element_id).
|
| scrollA | Scroll by mouse wheel ticks. With ``element_id``, moves the cursor to that element's position
first, then scrolls — useful for scrolling inside a specific list,
panel, or container. Without it, scrolls at the current cursor
position.
Args:
direction: One of "up", "down", "left", "right".
amount: Number of scroll ticks (default 3).
element_id: Optional element to scroll at. When given, cursor
is moved to the element's center first.
|
| activate_windowA | Bring a window to the foreground. Element-scoped actions (click, set_value, select_text, etc.) bring
their window to focus automatically — you rarely need this. Use it
when you need to type_text or press_key in a window without first
clicking an element in it (e.g. sending a keyboard shortcut to a
window you haven't interacted with yet in this task).
Args:
window_id: The window ID to activate (from windows()).
|
| minimize_windowA | Minimize a window to the dock/taskbar. Use windows() to find the window ID first.
To restore a minimized window, use activate_window().
Args:
window_id: The window ID to minimize.
|
| fullscreen_windowA | Enter or exit fullscreen for a window. Use windows() to find the window ID first.
Args:
window_id: The window ID.
fullscreen: True to enter fullscreen (default), False to exit.
|
| close_windowB | Close a window. Use windows() to find the window ID first.
Args:
window_id: The window ID to close.
|
| move_windowB | Move a window to a new screen position. Use windows() to find the window ID first.
Args:
window_id: The window ID to move.
x: New horizontal position of the top-left corner.
y: New vertical position of the top-left corner.
|
| resize_windowA | Resize a window. Use windows() to find the window ID first.
Args:
window_id: The window ID to resize.
width: New width in pixels.
height: New height in pixels.
|
| wait_forA | Wait for elements to appear or disappear. Polls until matching elements are found (or gone) or timeout.
Use after actions that trigger UI changes.
Args:
element: Text to search for. Pass a single string (e.g.
"Submit") or a list of strings (e.g. ["Success", "Error"])
for multi-query mode. With mode="any", returns as soon
as any query matches. With mode="all", waits until every
query has matched.
app: Scope to this application.
window_id: Scope to this window.
role: Only match this role.
states: Only match elements with ALL these states.
fields: Which fields to search (default: ["name"]).
mode: "any" (return when any query matches) or "all"
(wait for all queries to match). Only meaningful when
element is a list.
timeout: Maximum seconds to wait (default 10).
source: "full" (default), "cdp_ax", "native", or "dom".
"ax" remains as a compatibility alias for "cdp_ax".
max_results: Maximum elements to return (default 5).
wait_for_new: If true, ignore elements already present -- wait for NEW ones.
gone: If true, wait for matching elements to DISAPPEAR instead.
|
| wait_for_appA | Wait for an application to appear or disappear. Polls the application list until the app is found (or gone).
Use after launching or closing an application.
Args:
app: Application name to wait for (e.g. "Firefox", "Slack").
timeout: Maximum seconds to wait (default 10).
gone: If true, wait for the app to DISAPPEAR instead.
|
| wait_for_windowA | Wait for a window to appear or disappear. Polls the window list until a window with a matching title is
found (or gone). Use after actions that open or close windows.
When found, auto-activates the window so subsequent type_text
and press_key target it.
Args:
title: Window title to search for (substring match).
app: Only look for windows in this application.
timeout: Maximum seconds to wait (default 10).
gone: If true, wait for the window to DISAPPEAR instead.
|
