Skip to main content
Glama

act_window

Destructive

Run a sequence of UI steps in one window, stopping at the first failure. Performs clicks, typing, keys, set, actions, scroll, drag, focus, and wait by element ref or screenshot pixels.

Instructions

Run steps in one window, in order, stopping at the first that fails: click, type, key, set, action, scroll, drag, focus, wait. Targets are e-refs from read_window or [x, y] pixels of its read_screenshot; drag takes pixels of a whole-screen read_screenshot. Element clicks, set and action never bring the window to the front; keys and typing don't on Hyprland, elsewhere they focus it. Mouse steps ([x, y] clicks, right or double clicks, scroll, drag) need a focus step first, which shows the window to the user. focused: true sends keys to the focused window, refused if the focus moved. then: tree (default after read_window) or screenshot (brings the window forward except on Hyprland) shows the result.

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": {
      "window": "<window>",
      "steps": "<steps>"
    },
    "name": "act_window"
  }
}

Input Schema

NameRequiredDescriptionDefault
thenNo
stepsYes
windowYesWindow id from read_windows

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already flag destructive/openWorld, and the description goes well beyond them: failure semantics (stop at first failing step), platform-specific focus behavior on Hyprland vs elsewhere, the rule that a focus step visibly brings the window to the front, and that focused:true is refused if focus moved. These are exactly the side effects an agent needs before firing off input events.

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?

Front-loads the core behavior in the first sentence and then attaches each caveat to the step type it governs, with zero repeated or filler wording. Dense but every clause carries operational meaning.

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 tool whose complexity lives in a nested step union, the description covers ordering, targeting, focus prerequisites, and result retrieval ('then'). No output schema exists, so it does well to explain that 'then' surfaces the result tree or screenshot, though it could say more about error reporting when a step fails.

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 only 33%, but the description compensates for the non-obvious pieces: e-ref vs pixel target semantics, that drag coordinates come from a whole-screen screenshot, the meaning of focused:true, and the default value of 'then'. The 'window' id parameter is left to the schema, which already documents it.

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?

States a specific verb and scope: 'Run steps in one window, in order, stopping at the first that fails', then enumerates the exact step vocabulary (click, type, key, set, action, scroll, drag, focus, wait). This clearly separates it from the read_* siblings, which gather information rather than act.

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 concrete conditions: targets come from read_window or read_screenshot, mouse steps need a preceding focus step, and 'then' defaults to tree after read_window. It stops short of an explicit 'do not use this for X' routing statement, so guidance is strong but not exhaustive.

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