window_list

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

With no annotations, the description carries the full burden. It discloses that it lists windows optionally filtered by app bundle id or name, and that it returns window_ref handles for subsequent window_focus/window_manage operations. While it doesn't mention read-only nature explicitly, 'List' implies a non-mutating behavior. Some details like on_screen_only behavior or permissions are omitted, but the core behavior is transparent.

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

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

The description is two sentences long, front-loaded with the main action, and every sentence provides useful information. No redundant or vague wording.

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

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

Given the lack of annotations, output schema, and schema descriptions, the description is quite complete: it indicates the purpose, filtering capability, and return value purpose. The only minor gap is the lack of explicit mention of the on_screen_only parameter's effect, but the overall tool behavior is clear for a simple list operation.

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

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

The description explains the 'app' parameter by stating it can be a bundle id or name, adding value beyond the schema. However, the 'on_screen_only' parameter is not mentioned at all, and with 0% schema description coverage, the description must compensate for both parameters. It only partially does so.

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

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

The description clearly states the tool's purpose with a specific verb ('List windows') and resource, and distinguishes it from sibling tools like window_focus and window_manage by noting it returns handles for those tools. It also indicates the optional filtering by app.

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

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

The description provides clear context for when to use the tool: when you need to enumerate windows and obtain window_ref handles for focusing/managing. It does not explicitly exclude alternatives, but no other sibling tool offers this functionality, making the usage context clear.

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