Skip to main content
Glama

macos_mouse_drag

Press, drag to an absolute target, and release on macOS to control sliders, selections, resizing, drawing, and drag-and-drop, with optional waypoints, held modifiers, and pauses.

Instructions

macOS only. Press the mouse button at the current cursor position, drag to an absolute target in logical coordinates, and release. Use for sliders, selections, resizing, drawing and drag-and-drop, optionally through waypoints, with modifiers held, and with pauses after the press and before the release. Position the cursor at the drag start first (macos_mouse_move). Inside a browser tab, tab_drag targets page elements exactly instead. Requires Accessibility permission.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "x": "<x>",
      "y": "<y>"
    },
    "name": "macos_mouse_drag"
  }
}

Input Schema

NameRequiredDescriptionDefault
xYesAbsolute target X in logical points (top-left origin).
yYesAbsolute target Y in logical points (top-left origin).
pathNoPoints the pointer passes through, in order, between the start and the target, without stopping: draw a stroke or go around an obstacle. A pause on the way (hovering over a folder until it springs open) is not supported; dwellMs pauses on the final target, then releases. Defaults to a straight line.
buttonNoWhich button to hold during the drag. Defaults to left.
holdMsNoMilliseconds the button stays down before the pointer moves. Defaults to 10; give 300 to 600 for a list or app that starts a drag only after a long press.
dwellMsNoMilliseconds the pointer rests on the target before the release. Defaults to 10; give 300 or more for a target that reacts to hovering (a sortable list making room, a folder springing open).
modifiersNoModifiers held for the whole drag: Shift (constrain), Alt/Option (duplicate in design tools), Meta/Command, Control. They go down before the button and come up after it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full burden and does so: it discloses that the drag begins at the current cursor position (not a supplied parameter), that Accessibility permission is required, the modifier down/up ordering relative to the button, and the limitation that mid-path pauses are unsupported (only dwellMs on the final target). A rare, explicit failure-boundary statement ('A pause on the way... is not supported') is exactly the kind of context annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with 'macOS only' and the core press-drag-release sequence, so the essential mechanics land first. The middle sentence is dense, stacking use cases, waypoints, modifiers and pauses into one long clause, but every element maps to a real parameter or constraint and nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with no annotations and no output schema, the description covers permission requirements, ordering semantics, drag-start precondition, sibling alternatives and an explicit behavioral limitation. The only gap is what happens after the release (return value or failure signaling), which is minor for a gesture tool likely returning nothing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains x, y, path, button, holdMs, dwellMs and modifiers, which sets a baseline of 3. The description still adds meaning beyond it by clarifying that x/y is the release target while the press point is the current cursor, and by framing holdMs/dwellMs as pauses after press and before release; the waypoint-vs-dwell distinction is reinforced rather than merely repeated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource pair ('Press the mouse button... drag to an absolute target... and release') and immediately scopes it ('macOS only'). It distinguishes itself from two siblings by name, telling the agent to use macos_mouse_move to position the cursor first and tab_drag for in-page elements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names concrete use cases (sliders, selections, resizing, drawing, drag-and-drop) and explicit alternatives: macos_mouse_move for placing the drag start, and tab_drag when inside a browser tab. The key precondition, that the cursor must already be at the drag origin, is stated rather than implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.