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

Goes well beyond the readOnly/destructive annotations: discloses that the tree is pruned to signal-bearing nodes and bounded by max_depth plus a node budget, so very large windows return partial results. Also explains that the macOS menu bar is skipped by default because it contributes hundreds of nodes, which is a real behavioral caveat an agent needs.

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?

Front-loaded with purpose and the ui_click ref payoff, then alternatives, then caveats. Dense with parentheticals and em-dashes, but every clause carries information; nothing is filler.

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?

For a zero-required-parameter discovery tool with an output schema, it covers everything an agent needs: what comes back, that the result may be partial, what a node's ref is good for, and how to widen scope. No gaps remain that would cause a misinvocation.

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?

With 100% schema coverage the baseline is 3, but the description adds rationale the schema lacks: why include_menu_bar defaults false (hundreds of menu-item nodes), the default depth of 12, and where to get app_bundle_id (list_windows). It does not add much for window_id, whose activation caveat already lives in the 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?

States a specific verb+resource (returns a compact accessibility tree of a running native app's labeled and interactive elements) and scopes it precisely (pruned to signal-bearing nodes). It explicitly distinguishes itself from ui_find_element and from web_read's a11y mode, so an agent can pick it without opening the schema.

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?

Gives an explicit use case — discover what to act on in an unfamiliar app when the element's role/label isn't known — and names the sibling it is not for, with the reason (ui_find_element needs a label up front). It also states the condition for the non-default include_menu_bar flag rather than leaving it to the schema.

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