Skip to main content
Glama

manage_window

Focus, close, minimize, maximize, restore, move, or resize a window in a sandboxed app instance so agents can switch dialogs and arrange GUI targets.

Instructions

Act on a window of an instance: action='activate' (focus/raise — switch between an app's windows or dialogs), 'close' (asks the app to close it — a save prompt may appear), 'minimize', 'maximize', 'restore' (un-maximize), 'move' (to x,y), 'resize' (to width x height). window_id=0 means the active window (window_info lists ids).

Returns {"ok", "action", "instance", "window", "detail"} plus observe/settle_ms like click(). Fails (isError) if the window id is unknown, the action is unknown, move/resize sizes are missing, or the instance is down. maximize/restore need wmctrl (status().deps).

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": {
      "action": "<action>"
    },
    "name": "manage_window"
  }
}

Input Schema

NameRequiredDescriptionDefault
xNo
yNo
widthNo
actionYes
heightNo
observeNonone
instanceNo
settle_msNo
window_idNo
observe_regionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.6.1

TDQS

A4.3/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: it discloses side effects (close asks the app and may raise a save prompt), the return payload shape, and the precise failure conditions (unknown window id, unknown action, missing move/resize sizes, instance down). It also flags an external dependency (maximize/restore need wmctrl, checkable via status().deps), which is the kind of environment constraint an agent cannot infer elsewhere.

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?

Dense but front-loaded: the action taxonomy leads, then the window_id convention, then return/failure behavior and dependencies. Nothing is padding, though the parenthetical action glosses make sentences long and the 'like click()' reference assumes knowledge of a sibling.

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 mutation tool with no annotations and no output schema, the description supplies the return shape, error surface, side effects, and dependency requirements that would otherwise be missing. The residual gap is post-action feedback control (observe, observe_region, settle_ms) and whether move/resize coordinates are screen- or window-relative, neither of which is stated.

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

Parameters3/5

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

Schema description coverage is 0% across 10 params, and the description rescues the highest-value ones: action (with a full informal enum the schema lacks), window_id (0 = active, ids from window_info), and x/y/width/height for move/resize. However, observe, observe_region, settle_ms and instance are left essentially undefined — observe/settle_ms are only cross-referenced as 'like click()', forcing the agent to consult another tool's docs.

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?

Opens with a specific verb+resource ("Act on a window of an instance") and then enumerates every supported action with its meaning, so an agent immediately knows this is window-state manipulation rather than content interaction. It also anchors itself against siblings by naming window_info for ids and click() for the observe/settle convention.

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?

Each action carries usage context ('activate' = focus/raise to switch between an app's windows or dialogs; 'restore' = un-maximize; 'close' may trigger a save prompt), which effectively tells the agent which action to pick. It lacks explicit exclusions — e.g. that click()/type_text should be used to interact with window contents rather than this tool — so guidance is clear but not complete.

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