Skip to main content
Glama

screen_open_app

Idempotent

Take one of the user's apps for a demo, with the REAL mouse and keyboard while the user watches: brings its window to the front (maximised unless maximize=false) and returns what can be acted on (refs, roles, names, boxes in pixels from the window's top-left) with a screenshot. From now on screen_look, screen_act and screen_record_* work on this app. If the user moves the mouse, you are stopped.

response_detail (summary|ids|compact|full), fields (dotted paths), cursor (next page) — see the server instructions.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "screen_open_app"
  }
}

Input Schema

NameRequiredDescriptionDefault
hwndNo
titleNo
cursorNo
fieldsNo
maximizeNo
response_detailNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A3.6/5.0
Behavior4/5

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

Annotations only flag non-readOnly, non-destructive, idempotent, closed-world; the description adds the important context that real mouse and keyboard input is driven while the user watches, that the window is maximized by default (overridable), what the response contains (refs, roles, names, pixel boxes measured from the window's top-left, plus a screenshot), and that control is interrupted if the user takes the mouse. It does not say whether the target app's state or layout is altered, or what happens when no window matches.

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 main behavior is front-loaded in one dense but readable sentence, with consequences and abort condition following. The trailing parameter gloss is terse and defers to server instructions, which is efficient though slightly compressed.

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

Completeness3/5

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

With six optional parameters, no output schema, and 0% schema description coverage, the description does cover the return payload and the maximize behavior, which compensates for the missing output schema. However, app selection ('hwnd' vs 'title'), failure behavior, and differentiation from 'screen_open' are absent, so an agent could still call it incorrectly.

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 coverage is 0%, so the description must carry the parameter load; it explains 'maximize' (default true, disabled with maximize=false), 'response_detail' (summary|ids|compact|full), 'fields' (dotted paths), and 'cursor' (next page). It says nothing about 'hwnd' and 'title' — the two parameters that actually select the app and appear mutually exclusive — leaving the most consequential choice undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('Take one of the user's apps... brings its window to the front') plus the resulting state ('screen_look, screen_act and screen_record_* work on this app'), so the agent knows what the call accomplishes. It never explains how it differs from the sibling 'screen_open', which is the one distinction an agent most needs before choosing.

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

Usage Guidelines3/5

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

Usage is implied through the follow-on chain (open an app, then use screen_look/screen_act/screen_record), and the abort condition ('If the user moves the mouse, you are stopped') is a useful constraint. There is no explicit when-to-use guidance versus 'screen_open', 'screen_list_apps', or 'screen_hand_over', and no rule for choosing between the 'hwnd' and 'title' targeting parameters.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.