hypruse

Overview Schema Source Related Servers Discussions Admin

pointer

Destructive

Control the mouse cursor on Hyprland: move, click, drag, or scroll in global coordinates. Optionally capture desktop, screenshot, or focused window elements after the action.

Instructions

Mouse in global coordinates. action='move' (x,y) | 'click' (optional x,y first; button left/right/middle; double=true) | 'drag' (x,y → to_x,to_y holding button) | 'scroll' (scroll_dy notches, positive = content down; optional x,y first). then appends the result to this call so you skip a round-trip: 'desktop' a fresh snapshot, 'screenshot' a stable capture, 'ui' the focused window's elements with current values, 'none' (default) nothing. allow_auth=true overrides the refusal to click over a system authentication dialog. The pointer is the human's own cursor, so it never runs in the background: it is refused where the input would land on a window other than the one the human is in (press controls there with click_ui), unless background=false.

Input Schema

Name	Required	Default
`x`	No
`y`	No
`then`	No	none
`to_x`	No
`to_y`	No
`action`	Yes
`button`	No	left
`double`	No
`scroll_dx`	No
`scroll_dy`	No
`allow_auth`	No
`background`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.13.0Oct 19, 2026

addedInput schema / properties / background

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Background"
+}

Addedv0.9.4Jul 26, 2026
Removedv0.6.0Jul 17, 2026

Changed3 schema fields changedv0.5.0Jul 17, 2026

addedInput schema / properties / then

Added value: +{
+  "default": "none",
+  "title": "Then",
+  "type": "string"
+}

addedOutput schema / properties / result / anyOf

Added value: +[
+  {
+    "items": {},
+    "type": "array"
+  },
+  {
+    "type": "string"
+  }
+]

removedOutput schema / properties / result / type
```
Removed value: -"string"
```

First observedv0.1.1Jul 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only say destructiveHint=true; the description adds the crucial behavioral facts: the pointer is the human's own cursor and never runs in the background, calls are refused for non-focused windows unless background=false, and clicks over system auth dialogs are refused unless allow_auth=true. That 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 the action menu, and the per-action parentheses keep it tight despite a lot of content; no sentence is filler. It is dense to the point of being hard to parse on first read, which costs a point.

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?

An output schema exists, so return values need no explanation; annotations cover the safety profile; the description covers refusal conditions, mode trade-offs, and round-trip avoidance via `then`. For a destructive 12-parameter mutation tool this is complete enough to call correctly.

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?

With 0% schema description coverage across 12 parameters, the description carries the whole load and mostly succeeds: x/y, button values, double, to_x/to_y, scroll_dy direction, then-options, allow_auth and background are all explained. scroll_dx is never mentioned and the coordinate system is only implied by 'global coordinates'.

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?

Names the specific resource (the mouse/pointer) and scope (global coordinates), then enumerates every action with its argument shape: 'move' (x,y), 'click', 'drag', 'scroll'. It also distinguishes itself from the sibling click_ui by naming it as the fallback for other windows.

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

Usage Guidelines4/5

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

Gives a concrete routing rule: where the pointer would land on a window the human is not in, use click_ui instead, and use allow_auth to override the authentication-dialog refusal. Clear context, though it never states when a caller should prefer ui/desktop navigation generally over raw pointer actions.

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

Deploy Server