List windows

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds a real behavioral disclosure: password managers are never listed, which matters for interpreting incomplete results. It also explains the dialog↔owner relationship via dialogOf. Missing are ordering, whether dialogs are flat or nested, and any staleness/refresh caveat.

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?

One sentence, front-loaded with the resource and its fields, with the filter rule at the end. The parentheticals ('like the taskbar', 'a file "Open" box…') buy useful intuition without much bloat, though the ellipsis and analogy cost a little precision.

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?

With no output schema, the description does the work by naming the returned fields and the dialogOf relation, and by flagging the password-manager exclusion. It leaves the result shape ambiguous (are dialogs separate entries or nested?) and says nothing about ordering, which a listing tool arguably should.

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?

Schema coverage is 0%, so the description must carry the single parameter — and it does, defining filter as 'part of a title or app', i.e. substring matching against either field. It doesn't state case sensitivity or that omission means all windows, but the semantics are substantially clarified.

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 names a specific resource (application windows on the desktop) and enumerates the data each entry carries (id, app, title, pid), plus the distinct dialog case with dialogOf. It stops short of explicitly contrasting itself with the sibling 'window' (single-window) or 'act' tools, so an agent still infers the enumeration-vs-inspection split.

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?

'look at a dialog by its id or title' implies this listing is a discovery step that feeds the 'look' tool, and 'filter: part of a title or app' hints at narrowing. But there is no explicit statement of when to use this versus 'window', 'act' or 'launch', and no stated preconditions.

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