ui

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

With no annotations, the description carries full burden. It discloses important behaviors: the tree may not be available for certain apps, password fields never report contents, dropdowns may lack value, and click points are global requiring window focus. It also mentions that the tool returns elements with roles, names, and click points. The description does not contradict annotations (none provided).

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 detailed and well-structured, front-loading the main purpose. Each sentence adds value, though it is slightly long. There is no redundancy, and the technical details are clearly presented. It could be slightly more concise, but overall it is effective.

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 tool's complexity (accessibility tree with varying behavior), the description is remarkably complete. It explains limitations, fallback strategies, return format, and exceptions. It covers all aspects needed for correct invocation, including implicit output schema description. No output schema is provided, but the description compensates with clear return structure.

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 description coverage is 0%, so description must compensate. It thoroughly explains all three parameters: 'window' (address from desktop, default focused), 'name' (filters by accessible name, case-insensitive), and 'actionable' (default true, keeps interactive roles). It also describes the return structure, adding significant value beyond the input schema.

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?

Description clearly states it reads the accessibility tree and returns elements with click points, distinguishing it from sibling tools like screenshot (visual fallback) and pointer (clicking). It specifies the action 'Read a window's accessibility tree' and the resource 'elements...with GLOBAL click points'.

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 guidance on when to use the tool (to target a control by name without screenshot or pixel guessing), and when to fall back (when the tree is not exposed, like in terminals or Electron/Chrome). It also mentions limitations (password fields, dropdowns) and suggests alternatives (click_ui, screenshot). However, it does not explicitly state when NOT to use this tool versus specific siblings.

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