ui_press

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

With no annotations, the description carries the burden of behavioral disclosure. It does disclose key effects like submitting, dismissing, and navigating, and notes that an element can be focused first. However, it does not mention waiting behavior, repeated presses, modifier handling, or what happens after a key triggers navigation or a mutation, leaving some behavioral uncertainty.

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?

Three short sentences carry the core purpose, examples, optional-focus behavior, and usage context. There is no repetition of schema documentation and no filler; the most important 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?

The tool has 11 parameters and no annotations or output schema, so the description needs to provide enough decision context. It does this well by explaining when keyboard interaction is expected and what pressing keys accomplishes. The schema documents all parameter semantics, so the main remaining gap is lack of detail about post-press behavior and return values, which is minor given the tool's nature.

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%, so the baseline is 3. The description adds semantic value beyond the schema by explaining common key meanings (Enter submits, Tab moves on, Escape dismisses, arrows navigate lists/grids) and by clarifying that focusing an element is optional, which maps to the selector/text/testid parameters.

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 a specific verb+resource ('Press a key') and then gives concrete examples of supported keys and their typical effects (submit, dismiss, move through a list). It also differentiates this tool from pointer-based siblings by calling it 'the tool for keyboard-driven screens, where clicking the control is not how the application expects to be used.'

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 clearly states when to use the tool: for keyboard-driven screens rather than clicking a control. It implicitly tells the agent to prefer ui_click for clickable controls, but it does not explicitly compare against related keyboard/input tools such as ui_type or ui_fill.

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