ui_dump

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

No annotations are provided, so the description carries the full burden. It communicates a read-like, low-cost operation ('List', 'Cheaper') and a behavioral comparison to screenshot, but it does not explicitly state side-effect-freeness, platform prerequisites, or limitations such as whether Flutter-specific elements appear in the dump. This leaves room for agent uncertainty about what the call actually does behind the scenes.

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 tightly structured: a one-sentence purpose, a one-sentence use-case comparison, and a compact Args list. No filler or repetition, and the most decision-relevant information is front-loaded.

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 simple read tool with an output schema and fully documented parameters, the description is mostly complete. However, it does not mention platform scope or when to prefer Flutter-specific siblings, which could matter given the large sibling list and that Flutter widgets may not appear in a generic UI hierarchy dump.

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%, and the description fully compensates by explaining all four parameters: contains, clickable_only, limit, and serial. Each explanation adds meaning beyond the raw schema, such as 'case-insensitive filter on text, content description or id' and 'only return elements that accept taps.'

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 opens with 'List on-screen UI elements with their tap coordinates,' which names a specific verb, resource, and output. It also distinguishes itself from screenshot by claiming to be 'cheaper and more precise than a screenshot when you only need to find a control,' so an agent can tell it apart from a key sibling.

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 explicitly frames when to use this tool: 'Cheaper and more precise than a screenshot when you only need to find a control.' This gives clear context for choosing ui_dump over screenshot, though it does not discuss other siblings like flutter_widget_tree or when those should be preferred.

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