desktop-touch-mcp

Overview Schema Source Related Servers Discussions Admin

window_dock

Pin, unpin, or dock any Windows app to a screen corner; dock restores minimized windows, resizes, and sets always-on-top for terminal or reference windows.

Instructions

Purpose: Decorate a window: pin (always-on-top), unpin, or dock (move + resize + optional pin). Details: action='pin' makes window always-on-top until unpin/duration_ms. action='unpin' removes always-on-top. action='dock' positions to corner with width/height (default 480×360 bottom-right) and pins it unless pin:false. Minimized windows are automatically restored before docking. The title matches a shown window first; a hidden one (on another virtual desktop, or a minimised packaged app's content) is not docked or pinned — bring it back with focus_window first. Prefer: Use action='dock' for terminal/CLI window auto-positioning at session start. Use action='pin' alone when you only need always-on-top without moving or resizing. Caveats: Pin survives minimize/restore; explicit action='unpin' needed to release. Dock fails on elevated processes. Dock overrides any existing Win+Arrow snap arrangement. Examples: window_dock({action:'dock', title:'PowerShell', corner:'bottom-right', width:480, height:360}) window_dock({action:'pin', title:'Settings', duration_ms:5000}) window_dock({action:'unpin', title:'Settings'})

Input Schema

TableJSON Schema

Name	Required	Description	Default
`pin`	No	If true, set always-on-top so the docked window stays visible on top of other windows. Use window_dock(action='unpin') to remove the topmost flag later. Default true.
`title`	No	'pin' / 'unpin': Partial window title (case-insensitive) 'dock': Partial window title to dock (case-insensitive). Matches the first shown window containing this text (a minimised one counts; a hidden one — on another virtual desktop, or a minimised packaged app's content — does not). Example: 'Claude Code', 'メモ帳'.
`width`	No	Window width in pixels after docking. Default 480.
`action`	Yes	Action selector — one of: pin, unpin, dock. Per-action required fields are enforced at call time (see the tool description); this flat schema lists every action's fields as optional.
`corner`	No	Screen corner to snap the window to. Default 'bottom-right'.	bottom-right
`height`	No	Window height in pixels after docking. Default 360.
`margin`	No	Pixel padding between the window and the screen edge. Default 8.
`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).
`monitorId`	No	Monitor to dock on (from desktop_state({includeScreen:true})). Omit for primary monitor.
`duration_ms`	No	Auto-unpin after this many ms (0–60000). Omit to pin indefinitely.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv2.3.1Oct 13, 2026

addedInput schema / $schema

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

removedInput schema / additionalProperties
```
Removed value: -false
```
addedInput schema / properties / height / exclusiveMinimum
```
Added value: +0
```
addedInput schema / properties / height / maximum
```
Added value: +9007199254740991
```
addedInput schema / properties / margin / maximum
```
Added value: +9007199254740991
```
addedInput schema / properties / monitorId / maximum
```
Added value: +9007199254740991
```

changedInput schema / properties / title / description

Previous value: -"Partial window title (case-insensitive)"New value: +"'pin' / 'unpin': Partial window title (case-insensitive)\n'dock': Partial window title to dock (case-insensitive). Matches the first shown window containing this text (a minimised one counts; a hidden one — on another virtual desktop, or a minimised packaged app's content — does not). Example: 'Claude Code', 'メモ帳'."

addedInput schema / properties / width / exclusiveMinimum
```
Added value: +0
```
addedInput schema / properties / width / maximum
```
Added value: +9007199254740991
```

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

changedInput schema / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "const": "pin"
-      },
-      "duration_ms": {
-        "description": "Auto-unpin after this many ms (0–60000). Omit to pin indefinitely.",
-        "maximum": 60000,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "title": {
-        "description": "Partial window title (case-insensitive)",
-        "type": "string"
-      }
-    },
-    "required": [
-      "action",
-      "title"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "const": "unpin"
-      },
-      "title": {
-        "description": "Partial window title (case-insensitive)",
-        "type": "string"
-      }
-    },
-    "required": [
-      "action",
-      "title"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "const": "dock"
-      },
-      "corner": {
-        "default": "bottom-right",
-        "description": "Screen corner to snap the window to. Default 'bottom-right'.",
-        "enum": [
-          "top-left",
-          "top-right",
-          "bottom-left",
-          "bottom-right"
-        ],
-        "type": "string"
-      },
-      "height": {
-        "default": 360,
-        "description": "Window height in pixels after docking. Default 360.",
-        "type": "integer"
-      },
-      "margin": {
-        "default": 8,
-        "description": "Pixel padding between the window and the screen edge. Default 8.",
-        "minimum": 0,
-        "type": "integer"
-      },
-      "monitorId": {
-        "description": "Monitor to dock on (from desktop_state({includeScreen:true})). Omit for primary monitor.",
-        "minimum": 0,
-        "type": "integer"
-      },
-      "pin": {
-        "default": true,
-        "description": "If true, set always-on-top so the docked window stays visible on top of other windows. Use window_dock(action='unpin') to remove the topmost flag later. Default true.",
-        "type": "boolean"
-      },
-      "title": {
-        "description": "Partial window title to dock (case-insensitive). Matches the first visible window containing this text. Example: 'Claude Code', 'メモ帳'.",
-        "type": "string"
-      },
-      "width": {
-        "default": 480,
-        "description": "Window width in pixels after docking. Default 480.",
-        "type": "integer"
-      }
-    },
-    "required": [
-      "action",
-      "title"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "const": "pin"
+      },
+      "duration_ms": {
+        "description": "Auto-unpin after this many ms (0–60000). Omit to pin indefinitely.",
+        "maximum": 60000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "include": {
+        "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"
+      },
+      "title": {
+        "description": "Partial window title (case-insensitive)",
+        "type": "string"
+      }
+    },
+    "required": [
+      "action",
+      "title"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "const": "unpin"
+      },
+      "include": {
+        "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"
+      },
+      "title": {
+        "description": "Partial window title (case-insensitive)",
+        "type": "string"
+      }
+    },
+    "required": [
+      "action",
+      "title"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "const": "dock"
+      },
+      "corner": {
+        "default": "bottom-right",
+        "description": "Screen corner to snap the window to. Default 'bottom-right'.",
+        "enum": [
+          "top-left",
+          "top-right",
+          "bottom-left",
+          "bottom-right"
+        ],
+        "type": "string"
+      },
+      "height": {
+        "default": 360,
+        "description": "Window height in pixels after docking. Default 360.",
+        "type": "integer"
+      },
+      "include": {
+        "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"
+      },
+      "margin": {
+        "default": 8,
+        "description": "Pixel padding between the window and the screen edge. Default 8.",
+        "minimum": 0,
+        "type": "integer"
+      },
+      "monitorId": {
+        "description": "Monitor to dock on (from desktop_state({includeScreen:true})). Omit for primary monitor.",
+        "minimum": 0,
+        "type": "integer"
+      },
+      "pin": {
+        "default": true,
+        "description": "If true, set always-on-top so the docked window stays visible on top of other windows. Use window_dock(action='unpin') to remove the topmost flag later. Default true.",
+        "type": "boolean"
+      },
+      "title": {
+        "description": "Partial window title to dock (case-insensitive). Matches the first visible window containing this text. Example: 'Claude Code', 'メモ帳'.",
+        "type": "string"
+      },
+      "width": {
+        "default": 480,
+        "description": "Window width in pixels after docking. Default 480.",
+        "type": "integer"
+      }
+    },
+    "required": [
+      "action",
+      "title"
+    ],
+    "type": "object"
+  }
+]

Addedv1.1.1Apr 28, 2026
Removedv1.1.0Apr 27, 2026
Addedv1.0.3Apr 26, 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 carries the full burden and does so richly: pin survives minimize/restore and requires explicit unpin, minimized windows are auto-restored before docking, hidden windows are skipped, dock fails on elevated processes, and dock overrides existing Win+Arrow snap. These are exactly the side effects an agent needs before calling.

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

Conciseness5/5

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

Labeled sections (Purpose / Details / Prefer / Caveats / Examples) front-load the core purpose and keep each sentence earning its place. The three examples demonstrate distinct actions compactly.

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 10-parameter, no-annotation, no-output-schema mutation tool the coverage is strong: actions, defaults, and edge-case failure modes are all addressed. The only gap is that the response-shape opt-in (include/envelope) is left entirely to the schema.

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 100%, so baseline is 3, but the description adds essential per-action semantics the flat schema omits — the schema itself defers 'per-action required fields' to the description, and the Details section maps action to behavior (dock defaults 480×360 bottom-right, pin:false to skip topmost). It stops short of covering the include/response-shape opt-in.

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 opening states a specific verb and resource ('Decorate a window: pin, unpin, or dock') and immediately disambiguates each action. It distinguishes itself from siblings by naming focus_window as the tool to use first for hidden windows, so an agent can route correctly without opening schemas.

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 'Prefer' block gives explicit when-to-use guidance: dock for terminal/CLI auto-positioning at session start, pin alone when only always-on-top is needed. It also names the alternative (focus_window) and the condition ('hidden one ... is not docked') that selects it.

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

window_dock

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools