wait_for_element_visible

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

With no annotations, the description carries the burden, and it discloses two important behaviors: the default timeout of 7 seconds when timeout is 0 or None, and the exception raised if visibility is not achieved. This gives the agent clear failure-mode expectations. It does not describe return behavior, but that is less significant for a 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?

Three short sentences, each with a distinct purpose: what the tool does, timeout behavior, and failure behavior. The main action is front-loaded, and there is no redundant or filler wording.

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 two-parameter wait tool, the description covers the essential behavior, timeout default, and error condition, and an output schema exists so return-value details are not required. It does not describe selector syntax or explicitly distinguish visibility from presence, which would make it fully complete. Overall, an agent has enough to invoke it correctly in most 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?

The description adds meaning to the timeout parameter by specifying the null/0 default and the 7-second fallback, which is absent from the schema. The required selector parameter is only indirectly represented as 'element', and no selector syntax or format is given. Schema description coverage is 0%, so this remains a partial gap.

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 identifies a clear verb and resource: waiting until an element is visible on the page. The visibility condition and timeout failure are stated, so the tool's core job is unmistakable. It does not explicitly contrast with sibling wait/assert variants, which prevents a 5.

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 intended use is implied: call this when the agent must block until an element becomes visible. It does not state when to prefer wait_for_element_present or assert_element_visible, nor any exclusions. No alternatives or when-not-to-use guidance is provided.

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