list_windows
Screen, windows & UI · macOS · Windows
Effect: read (strongest supported action). Status: gated.
Gated means the tool requires an installed app, a connected account, permission, or runtime availability. Check those requirements on the listed platform before using it.
macOS
Purpose
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), 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. 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.
Required inputs
No required inputs are declared in this platform's schema. Optional selectors and runtime requirements may still apply.
Permissions and confirmation
No explicit confirmation parameter is exposed in this snapshot. This does not grant permission to act: obtain user authorization before any real action.
- Use only the apps, accounts and resources authorized by the user on this platform. Consult this tool's platform-specific description for its connection and permission requirements; this catalog does not assert additional OAuth scopes or OS entitlements.
Full input schema — macOS
{
"properties": {
"app_bundle_id": {
"description": "Only return windows owned by this app bundle id.",
"type": "string"
},
"on_screen_only": {
"description": "Only on-screen windows (default true).",
"type": "boolean"
}
},
"required": [],
"type": "object"
}Documentation example
Do not execute this example. These concrete inputs refer to a fictional demonstration dataset. Resolve real handles and obtain user authorization before any real call.
{}Windows
Purpose
Lists the open windows on this machine: window id, owning app (exe name), pid, title, bounds {x,y,w,h} and display id. Windows-only (uses the Win32 windowing API). Filter by app with app_bundle_id (an exe-name substring match on Windows).
Required inputs
No required inputs are declared in this platform's schema. Optional selectors and runtime requirements may still apply.
Permissions and confirmation
No explicit confirmation parameter is exposed in this snapshot. This does not grant permission to act: obtain user authorization before any real action.
- Use only the apps, accounts and resources authorized by the user on this platform. Consult this tool's platform-specific description for its connection and permission requirements; this catalog does not assert additional OAuth scopes or OS entitlements.
Full input schema — Windows
{
"properties": {
"app_bundle_id": {
"description": "Filter to windows owned by this app. On Windows, a case-insensitive substring of the exe name (e.g. 'chrome').",
"type": "string"
},
"on_screen_only": {
"description": "Only return visible, non-empty-title windows (default true).",
"type": "boolean"
}
},
"required": [],
"type": "object"
}Documentation example
Do not execute this example. These concrete inputs refer to a fictional demonstration dataset. Resolve real handles and obtain user authorization before any real call.
{}