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

TableJSON 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).

Schema Changelog

Changes observed during successful MCP inspections.

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.7/5.0

Behavior5/5

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

Annotations are minimal (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description carries the burden of behavioral disclosure. It candidly reveals failure modes (permission_required error, empty result due to Electron bundle-id mismatch, minimized windows omitted by default, Accessibility-dependent null minimized values), default behaviors (on_screen_only true, include_overlays false, include_minimized_state false), and stability guarantees (window_id stable within session). This is exemplary transparency beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but information-dense. Front-loads the primary purpose in the first sentence, but then packs a large number of behaviors, defaults, exceptions, and caveats into a single continuous prose paragraph. A future reader would benefit from bullets or clearer separation of parameters/behavioral notes. Every sentence earns its place but structure is not ideal.

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?

Given no output schema, the description enumerates all available output fields (window_id, bundle id, name, title, bounds, display_id, layer, is_focused, minimized) and explains the meaning of important ones (display_id matches list_displays, layer semantics). It explains return edge cases (empty note, permission error, null minimized) and covers the four parameters with contextual guidance. Nothing critical is missing for an agent to decide and call this tool 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?

All 4 params are already described in the schema with 100% coverage. The description nevertheless adds meaningful context: Electron bundle-id helper-process caveat for app_bundle_id, the exact visual meaning of layer for include_overlays, and the Accessibility/Accessibility-granted nuance for include_minimized_state including the extra lookup cost. It adds value above the schema, though it doesn't fully enumerate every edge case for on_screen_only.

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?

Description states a specific verb and resource ('Lists on-screen windows of any app') with a detailed inventory of returned fields, and differentiates itself from siblings like list_displays, window_focus, window_set_frame, and screenshot_capture through explicit mentions of window_id, display_id, and later targeting. It also clearly distinguishes itself from the many other list_* tools by scope (windows vs displays, emails, contacts, etc.).

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

Usage Guidelines5/5

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

Provides explicit when-to-use guidance: use on_screen_only true vs false, include_overlays true vs false, include_minimized_state true vs false, and warns about Electron helper-process bundle-id pitfalls. It names the permission requirement (Screen Recording) and conditions under which the tool errors. It also tells the agent to read the note when empty instead of concluding no windows. This is thorough, specific, and actionable.

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.

List Windows

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources