desktop-touch-mcp

Overview Schema Source Related Servers Discussions Admin

mouse_drag

Perform left-button drag from start to end coordinates—for sliders, drag-and-drop, canvas drawing, and window resizing—with automatic window guarding and delivery verification.

Instructions

Click and drag from (startX, startY) to (endX, endY) holding the left mouse button — for sliders, drag-and-drop, canvas drawing, and window resizing. Pass windowTitle so the server auto-guards the start coordinate and returns post.perception. Examples: mouse_drag({windowTitle:'Notepad', startX:50, startY:50, endX:200, endY:200}). lensId is optional and only for advanced pinned-target workflows. Caveats: Left button only. Both start and endpoint are guarded. Cross-window and desktop drags are blocked by default — pass allowCrossWindowDrag:true to confirm intent; that refusal is code:'CrossWindowDragBlocked'. A drag starting in a tabbed application's tab strip returns code:'TabDragBlocked' — pass allowTabDrag:true when tearing off or rearranging a tab is intended. hints.verifyDelivery:{status:'delivered'|'focus_only'|'unverifiable', reason} reports the post-drop observation in the same 3-value shape as mouse_click. MouseDragNotDelivered is SUGGESTS-registered but reserved-only (not emitted) — degradation is expressed via the 'unverifiable' status rather than a typed code. Win11 foreground refusal (UIPI cross-elevation / admin-only target / call from a background process or service) returns code:'ForegroundRestricted' ok:false from the homing path.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`endX`	Yes
`endY`	Yes
`hwnd`	No	Direct window handle ID (takes precedence over windowTitle). Obtain from get_windows response (hwnd field). String type to avoid 64-bit precision issues.
`speed`	No	Cursor movement speed in px/sec. 0 = instant.
`homing`	No	Enable homing correction if the target window moved.
`lensId`	No	Optional perception lens ID. Guards and envelope same as mouse_click.
`startX`	Yes
`startY`	Yes
`include`	No	Optional response-shape opt-in. `['envelope']` returns the self-documenting envelope (`_version` / `data` / `as_of` / `confidence`). `['raw']` forces raw shape (overrides DESKTOP_TOUCH_ENVELOPE=1 server default). Default behaviour is raw shape (compat with existing clients).
`narrate`	No	Narration level. rich includes UIA or browser state diff when supported, and is withheld with post.rich.diffDegraded when the diff cannot be shown to describe the window that was acted on.	minimal
`windowTitle`	No	Partial title of the target window.
`allowTabDrag`	No	When true, allow drags that start in the title-bar / tab-strip area of a tabbed app (Notepad, Terminal, Edge, Chrome, etc.). Default false — such drags are blocked because they detach the tab into a new window rather than moving the window. Pass true only when you intentionally want to rearrange or detach a tab. Note: active only when auto-guard is enabled (same scope as allowCrossWindowDrag).
`verifyDelivery`	Yes	Parameter 'verifyDeliveryParam' from the Windows server schema.
`allowCrossWindowDrag`	No	When true, allow dragging the endpoint into a different window or the desktop background. Default false — cross-window drags (including desktop/wallpaper) are blocked to prevent accidents. Pass true to confirm intent for deliberate cross-window or desktop-area drags.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.0.0Sep 24, 2026

changedInput schema / properties / narrate / description

Previous value: -"Narration level. rich includes UIA or browser state diff when supported."New value: +"Narration level. rich includes UIA or browser state diff when supported, and is withheld with post.rich.diffDegraded when the diff cannot be shown to describe the window that was acted on."

Addedv1.9.2May 25, 2026
Removedv1.8.0May 23, 2026
Addedv1.6.0May 16, 2026
Removedv1.5.1May 12, 2026
Addedv1.5.0May 12, 2026
Removedv1.4.3May 11, 2026
Addedv1.4.2May 10, 2026
Removedv1.4.0May 9, 2026

Changed1 schema field changedv1.2.1May 3, 2026

addedInput schema / properties / include

Added value: +{
+  "description": "Optional response-shape opt-in. `['envelope']` returns the self-documenting envelope (`_version` / `data` / `as_of` / `confidence`). `['raw']` forces raw shape (overrides DESKTOP_TOUCH_ENVELOPE=1 server default). Default behaviour is raw shape (compat with existing clients).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Addedv1.0.3Apr 26, 2026
Removedv0.15.7Apr 20, 2026

Changed1 schema field changedv0.15.4Apr 19, 2026

addedInput schema / properties / hwnd

Added value: +{
+  "description": "Direct window handle ID (takes precedence over windowTitle). Obtain from get_windows response (hwnd field). String type to avoid 64-bit precision issues.",
+  "type": "string"
+}

Changed1 schema field changedv0.15.3Apr 18, 2026

addedInput schema / properties / allowTabDrag

Added value: +{
+  "default": false,
+  "description": "When true, allow drags that start in the title-bar / tab-strip area of a tabbed app (Notepad, Terminal, Edge, Chrome, etc.). Default false — such drags are blocked because they detach the tab into a new window rather than moving the window. Pass true only when you intentionally want to rearrange or detach a tab. Note: active only when auto-guard is enabled (same scope as allowCrossWindowDrag).",
+  "type": "boolean"
+}

Changed1 schema field changedv0.13.1Apr 17, 2026

addedInput schema / properties / allowCrossWindowDrag

Added value: +{
+  "default": false,
+  "description": "When true, allow dragging the endpoint into a different window or the desktop background. Default false — cross-window drags (including desktop/wallpaper) are blocked to prevent accidents. Pass true to confirm intent for deliberate cross-window or desktop-area drags.",
+  "type": "boolean"
+}

Changed13 schema fields changedv0.10.0Apr 16, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

addedInput schema / additionalProperties
```
Added value: +false
```

removedInput schema / properties / _stub

Removed value: -{
-  "description": "Stub tool — arguments ignored."
-}

addedInput schema / properties / endX
```
Added value: +{
+  "type": "number"
+}
```
addedInput schema / properties / endY
```
Added value: +{
+  "type": "number"
+}
```

addedInput schema / properties / homing

Added value: +{
+  "default": true,
+  "description": "Enable homing correction if the target window moved.",
+  "type": "boolean"
+}

addedInput schema / properties / lensId

Added value: +{
+  "description": "Optional perception lens ID. Guards and envelope same as mouse_click.",
+  "type": "string"
+}

addedInput schema / properties / narrate

Added value: +{
+  "default": "minimal",
+  "description": "Narration level. rich includes UIA or browser state diff when supported.",
+  "enum": [
+    "minimal",
+    "rich"
+  ],
+  "type": "string"
+}

addedInput schema / properties / speed

Added value: +{
+  "description": "Cursor movement speed in px/sec. 0 = instant.",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / startX
```
Added value: +{
+  "type": "number"
+}
```
addedInput schema / properties / startY
```
Added value: +{
+  "type": "number"
+}
```

addedInput schema / properties / windowTitle

Added value: +{
+  "description": "Partial title of the target window.",
+  "type": "string"
+}

addedInput schema / required

Added value: +[
+  "startX",
+  "startY",
+  "endX",
+  "endY"
+]

First observedv0.6.2Apr 14, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations, the description fully discloses behavioral traits: left-button only, both start and endpoint guarded, cross-window and tab drags blocked by default with specific error codes, verification status reporting, homing correction, and Win11 foreground restrictions. It also explains that MouseDragNotDelivered is reserved-only, showing deep transparency.

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?

The description is dense and information-rich, front-loaded with purpose and examples, followed by caveats. It is longer than ideal but every sentence adds critical operational detail. The structure flows from core action to edge cases, making it usable despite the length.

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

Completeness5/5

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

Given 14 parameters, no output schema, and no annotations, the description covers all essential behavioral aspects: error codes, verification, guards, exceptions, and even server-specific refusal conditions. It leaves no critical operational gap for an agent to infer.

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 coverage is 71%, so the description compensates for missing schema descriptions on startX/startY/endX/endY by illustrating them in the example. It adds meaning to verifyDelivery (3-value shape) and clarifies the purpose of windowTitle, allowCrossWindowDrag, and allowTabDrag. Minor gap: no explicit description of the coordinate semantics beyond the example, but it's sufficient.

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 clearly states the action (click and drag), the resource (mouse coordinates), and specific use cases (sliders, drag-and-drop, canvas drawing, window resizing). It differentiates from mouse_click by specifying the drag behavior and includes an explicit example with parameter names.

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?

The description provides explicit guidance on when to use the tool (e.g., for drag operations) and when to use specific flags (allowCrossWindowDrag, allowTabDrag) to override default blocks. It also mentions advanced lensId workflows, giving clear context for parameter choices.

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

mouse_drag

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools