ui_find_element

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

With no annotations, the description carries the full burden. It states the action and that positions are returned, but it does not disclose whether the operation is read-only, what happens if no element is found, or whether it returns the first match or all matches. The provided behavior is basic but not misleading.

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 a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose and outcome.

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 low complexity (2 params, no nested objects) and the absence of an output schema, the description adequately indicates the return value ('positions'). However, it could be more complete by specifying whether multiple matches are returned or how positions are formatted, but this is a minor gap for such a straightforward tool.

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 100% since both parameters (query and strategy) have descriptions in the schema. The description adds little beyond the schema—it restates that the query can be text, aria-label, or CSS, which the schema already details. No additional semantic value is provided.

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 uses a specific verb 'Find' with a clear resource 'UI elements' and specifies search methods (text, aria-label, CSS selector) and the outcome (return positions). This clearly distinguishes it from sibling tools like ui_click or ui_hover, which perform actions rather than locating elements.

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 implies the tool is used to locate UI elements before interaction, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. The context of sibling tools suggests a pre-interaction step, but the description itself provides no explicit guidance.

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