Local MCP

List Windows

list_windows

Read-only

Lists on-screen windows of any app with window_id, owning app bundle id + name, title, bounds (global space, top-left, points), display_id (the CGDirectDisplayID — matches list_displays, so you can look up which display a window is on), layer (0 = normal app window; non-zero = panel/overlay/menu), and is_focused. Window TITLES require Screen Recording permission — without it this returns an explicit permission_required error rather than a title-less result. Optional app_bundle_id filter — note that Electron-style apps often own their windows from a HELPER process with a different bundle id, so a filter can come back empty while the app is plainly on screen. on_screen_only DEFAULTS TO TRUE and excludes minimized, hidden and other-Space windows; pass false to see them. include_overlays DEFAULTS TO FALSE and excludes non-zero-layer windows (Notification Center, widgets, menus); pass true to include them — use layer in the result to tell them apart from normal windows. include_minimized_state DEFAULTS TO FALSE (an extra Accessibility lookup per app, so it's opt-in); pass true to add minimized (true/false) to each window AND, when on_screen_only is true (the default), also bring back the minimized windows that filter would otherwise drop — WITHOUT Accessibility granted minimized is null (unknown) and no minimized windows are added back, never a guessed false, so you can find/capture a minimized window without bringing it forward first. When the result is empty this tool returns a note explaining which filter emptied it and what to pass instead — read it instead of concluding the app has no windows. window_id is stable within the session for later targeting.

Input Schema

Name	Required	Description
`app_bundle_id`	No	Only return windows owned by this app bundle id.
`on_screen_only`	No	Only on-screen windows (default true).
`include_overlays`	No	Include non-zero-layer windows — Notification Center, desktop widgets, menus (default false).
`include_minimized_state`	No	Add `minimized` (true/false) to each window via an Accessibility lookup; null without Accessibility granted (default false).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 10, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "type": "object"
+}

Changed2 schema fields changedSep 30, 2026

addedInput schema / properties / include_minimized_state

Added value: +{
+  "description": "Add `minimized` (true/false) to each window via an Accessibility lookup; null without Accessibility granted (default false).",
+  "type": "boolean"
+}

addedInput schema / properties / include_overlays

Added value: +{
+  "description": "Include non-zero-layer windows — Notification Center, desktop widgets, menus (default false).",
+  "type": "boolean"
+}

Changed2 schema fields changedSep 29, 2026

removedInput schema / properties / include_minimized_state

Removed value: -{
-  "description": "Add `minimized` (true/false) to each window via an Accessibility lookup; null without Accessibility granted (default false).",
-  "type": "boolean"
-}

removedInput schema / properties / include_overlays

Removed value: -{
-  "description": "Include non-zero-layer windows — Notification Center, desktop widgets, menus (default false).",
-  "type": "boolean"
-}

Changed1 schema field changedSep 25, 2026

addedInput schema / properties / include_minimized_state

Added value: +{
+  "description": "Add `minimized` (true/false) to each window via an Accessibility lookup; null without Accessibility granted (default false).",
+  "type": "boolean"
+}

Changed1 schema field changedSep 25, 2026

addedInput schema / properties / include_overlays

Added value: +{
+  "description": "Include non-zero-layer windows — Notification Center, desktop widgets, menus (default false).",
+  "type": "boolean"
+}

AddedJul 10, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare readOnly/destructive/openWorld; the description carries the real behavioral load: titles require Screen Recording (else an explicit permission_required error), minimized state requires Accessibility (else null, 'never a guessed false'), per-app Accessibility lookup cost, and an empty-result `note` that explains which filter emptied the result. window_id session stability is also disclosed.

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?

It is a long single paragraph, but it is front-loaded (purpose and returned fields first, flags after) and nearly every clause carries non-obvious default/permission/interaction information. Capitalized DEFAULTS/HELPER emphasis aids scanning; bullet formatting would improve it further.

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?

With an output schema present, return-value documentation is optional, yet the description still covers fields, permissions, defaults, failure modes and the empty-result note. An agent has everything needed to call it correctly and interpret an empty response.

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 genuine meaning beyond the schema: the Electron HELPER-process bundle-id caveat for app_bundle_id, the precise set of windows on_screen_only excludes, using `layer` to distinguish overlays, and the cross-parameter interaction where include_minimized_state plus the on_screen_only default restores otherwise-dropped minimized windows.

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 ('Lists on-screen windows of any app') and enumerates the returned fields, so the agent immediately knows this is a read-only window enumeration distinct from window_focus/window_set_frame. Scope and output shape are unambiguous without opening the schema.

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 explicit when/when-not guidance for every flag: on_screen_only DEFAULTS TO TRUE and excludes minimized/hidden/other-Space windows, include_overlays DEFAULTS TO FALSE, include_minimized_state is opt-in and 'lets you find/capture a minimized window without bringing it forward first'. It does not name sibling alternatives (e.g. window_focus) for follow-up actions, so it stops short of a 5.

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

All Local MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.