wait_for_element

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It does add 'polling at regular intervals,' but it does not say what happens on timeout, whether the element must be visible or merely present in the hierarchy, or whether the tool returns a boolean or raises an error. This is a significant gap for a blocking wait operation.

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 sentence with no wasted words. It front-loads the core action and then adds the polling detail. Every clause contributes meaning.

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 wait tool with no output schema and no annotations, the description is incomplete. Schema covers parameters, but the description lacks timeout failure behavior, return/error semantics, and any comparison to sibling wait or visibility tools. An agent cannot fully predict how the tool behaves in edge cases.

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 schema fully documents text, resource_id, timeout_ms, poll_interval_ms, and device_id. The description's generic 'matching the query' adds no parameter detail beyond the schema, which is acceptable at the baseline 3.

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 states a specific verb and resource: 'Wait until a UI element matching the query appears on screen' with explicit polling behavior. It distinguishes this from sibling wait_for_text, wait_for_activity, find_element, and assertion tools without requiring schema inspection.

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 gives no guidance about when to prefer this tool over wait_for_text, assert_visible, find_element, or is_element_visible. It also does not state exclusions or mention that wait_for_text is a specialized alternative. An agent must infer the intended use from the name and sibling list.

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