Mouse¶

Mouse tools provide low-level positional control over the browser's mouse pointer. Use these tools when you need to interact with elements that are not in the accessibility snapshot, trigger hover effects at specific coordinates, compose custom gesture sequences with browser_mouse_down / browser_mouse_up, or perform pixel-precise drag operations. When a target element is visible in browser_snapshot, prefer the higher-level ref-based tools (browser_click, browser_hover, browser_drag) — they are more stable across layout changes.

Examples below focus on tool-specific data. Registered tools also return the shared operation metadata and error fields.

Optional page_id selects a live page without changing the selected tab; an invalid explicit target returns page_not_found. Frame-capable calls also accept frame_id and return frame_not_found for a detached or foreign frame. Omitted targets retain existing behavior. See explicit targeting.

browser_mouse_click_xy¶

Click the mouse at a viewport position on the active page.

All click, move and drag coordinates on this page use CSS pixels relative to the main frame's viewport, with (0, 0) at its top-left corner. They are not document coordinates; account for scrolling when choosing a target position.

Signature

async def browser_mouse_click_xy(
    instance: str,
    x: int,
    y: int,
    button: str = "left",
    click_count: int = 1,
    delay_ms: int = 0,
    *,
    page_id: str | None = None,
    wait_for: WaitForSpec | None = None,
) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`x`	`int`	—	Viewport-relative horizontal CSS pixel coordinate (0 = left edge).
`y`	`int`	—	Viewport-relative vertical CSS pixel coordinate (0 = top edge).
`button`	`str`	`"left"`	One of `"left"`, `"right"`, `"middle"`.
`click_count`	`int`	`1`	Number of clicks to deliver; use `2` for a double-click.
`delay_ms`	`int`	`0`	Delay in milliseconds between mousedown and mouseup.
`page_id`	`str \\| None`	`None`	Stable page ID; omitted uses the selected page. Explicit targeting preserves selection and rejects unavailable IDs.
`wait_for`	`WaitForSpec \\| None`	`None`	One condition armed before the action; see action observations.

Returns — see response envelope. data shape:

{ "clicked_at": [120, 340], "button": "left" }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
modal_state_blocked
invalid_params — unsupported mouse button
internal_error

Example

Request:

{ "name": "browser_mouse_click_xy", "arguments": { "instance": "main", "x": 120, "y": 340 } }

Response:

{ "status": "success", "instance": "main", "data": { "clicked_at": [120, 340], "button": "left" } }

Notes — Prefer browser_click(ref=...) when the target element is in the accessibility snapshot — it is more reliable and does not depend on exact layout coordinates.

browser_mouse_move_xy¶

Move the mouse cursor to an absolute pixel position without clicking.

Signature

async def browser_mouse_move_xy(instance: str, x: int, y: int, *, page_id: str | None = None) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`x`	`int`	—	Target horizontal pixel coordinate.
`y`	`int`	—	Target vertical pixel coordinate.
`page_id`	`str \\| None`	`None`	Stable page ID; omitted uses the selected page. Explicit targeting preserves selection and rejects unavailable IDs.

Returns — see response envelope. data shape:

{ "moved_to": [120, 340] }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
modal_state_blocked
internal_error

Example

Request:

{ "name": "browser_mouse_move_xy", "arguments": { "instance": "main", "x": 120, "y": 340 } }

Response:

{ "status": "success", "instance": "main", "data": { "moved_to": [120, 340] } }

Notes — Useful for triggering hover effects at specific coordinates. Prefer browser_hover(ref=...) when the target is in the accessibility snapshot. Use before browser_mouse_wheel when targeting a specific scrollable container.

browser_mouse_down¶

Press a mouse button down without releasing it.

Signature

async def browser_mouse_down(instance: str, button: str = "left", *, page_id: str | None = None) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`button`	`str`	`"left"`	One of `"left"`, `"right"`, `"middle"`.
`page_id`	`str \\| None`	`None`	Stable page ID; omitted uses the selected page. Explicit targeting preserves selection and rejects unavailable IDs.

Returns — see response envelope. data shape:

{ "button_down": "left" }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
modal_state_blocked
invalid_params — unsupported mouse button
internal_error

Example

Request:

{ "name": "browser_mouse_down", "arguments": { "instance": "main", "button": "left" } }

Response:

{ "status": "success", "instance": "main", "data": { "button_down": "left" } }

Notes — Pair with browser_mouse_up to complete a press-and-release sequence. For drag operations, prefer browser_mouse_drag_xy which handles the full sequence.

browser_mouse_up¶

Release a previously pressed mouse button.

Signature

async def browser_mouse_up(instance: str, button: str = "left", *, page_id: str | None = None) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`button`	`str`	`"left"`	Must match the button passed to `browser_mouse_down`.
`page_id`	`str \\| None`	`None`	Stable page ID; omitted uses the selected page. Explicit targeting preserves selection and rejects unavailable IDs.

Returns — see response envelope. data shape:

{ "button_up": "left" }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
modal_state_blocked
invalid_params — unsupported mouse button
internal_error

Example

Request:

{ "name": "browser_mouse_up", "arguments": { "instance": "main", "button": "left" } }

Response:

{ "status": "success", "instance": "main", "data": { "button_up": "left" } }

browser_mouse_drag_xy¶

Drag the mouse from one absolute pixel position to another.

Signature

async def browser_mouse_drag_xy(
    instance: str,
    from_x: int,
    from_y: int,
    to_x: int,
    to_y: int,
    *,
    page_id: str | None = None,
    wait_for: WaitForSpec | None = None,
) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`from_x`	`int`	—	Starting horizontal pixel coordinate.
`from_y`	`int`	—	Starting vertical pixel coordinate.
`to_x`	`int`	—	Ending horizontal pixel coordinate.
`to_y`	`int`	—	Ending vertical pixel coordinate.
`page_id`	`str \\| None`	`None`	Stable page ID; omitted uses the selected page. Explicit targeting preserves selection and rejects unavailable IDs.
`wait_for`	`WaitForSpec \\| None`	`None`	One condition armed before the action; see action observations.

Returns — see response envelope. data shape:

{ "from": [50, 100], "to": [300, 100] }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
modal_state_blocked
internal_error

Example

Request:

{
  "name": "browser_mouse_drag_xy",
  "arguments": { "instance": "main", "from_x": 50, "from_y": 100, "to_x": 300, "to_y": 100 }
}

Response:

{ "status": "success", "instance": "main", "data": { "from": [50, 100], "to": [300, 100] } }

Notes — Performs: move to (from_x, from_y), press left button, move to (to_x, to_y), release. For element-to-element drag, prefer browser_drag(source_ref, target_ref) which uses accessibility refs and is more stable across layout changes.

Once the press begins, the tool attempts a bounded button release even if the drag fails or is cancelled. Cleanup preserves the original failure. A failed or timed-out drag can still have moved page content; inspect the resulting state before retrying.

browser_mouse_wheel¶

Scroll the mouse wheel by the given pixel deltas at the current cursor position.

Signature

async def browser_mouse_wheel(
    instance: str,
    delta_x: int = 0,
    delta_y: int = 0,
    *,
    page_id: str | None = None,
    wait_for: WaitForSpec | None = None,
) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`delta_x`	`int`	`0`	Horizontal scroll in CSS pixels (positive = right).
`delta_y`	`int`	`0`	Vertical scroll in CSS pixels (positive = down).
`page_id`	`str \\| None`	`None`	Stable page ID; omitted uses the selected page. Explicit targeting preserves selection and rejects unavailable IDs.
`wait_for`	`WaitForSpec \\| None`	`None`	One condition armed before the action; see action observations.

Returns — see response envelope. data shape:

{ "scrolled": [0, 300] }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
invalid_params
modal_state_blocked
internal_error

Example

Request:

{ "name": "browser_mouse_wheel", "arguments": { "instance": "main", "delta_y": 300 } }

Response:

{ "status": "success", "instance": "main", "data": { "scrolled": [0, 300] } }

Notes — At least one of delta_x or delta_y must be non-zero; providing both as 0 returns an invalid_params error immediately. The scroll is delivered at the current cursor position — call browser_mouse_move_xy first to target a specific scrollable container.