Wait For Text

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, so the safety profile is covered. The description adds substantial behavior beyond that: it reads only rendered text (display:none excluded, iframe text excluded), a bad regex fails immediately, and a timeout reports waitedMs plus the last poll's findings. These are real operational traits an agent benefits from, though return shape is not exhaustively specified.

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?

Front-loaded with the core purpose, then sibling differentiation, then caveats, then conventions. Four dense sentences with little waste, though the caveat and convention clauses add density that a shorter form might trim.

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?

No output schema exists, and the description compensates by describing the timeout failure payload (waitedMs and last-poll findings). It covers visibility scope, regex failure behavior, and the timeout ceiling, leaving only fine-grained return details unstated.

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 100%, so all seven parameters are already documented, including regex/texts combination semantics, state enum, and the timeout cap. The description echoes the regex-plus-texts combination and timeout convention but adds no syntax or format detail beyond the schema; baseline 3 is appropriate.

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?

States a specific action (poll) on a specific resource (visible text of the page or a scope selector), including both 'appears' and 'disappears' directions. It explicitly delineates itself from the sibling wait_for_selector, letting an agent choose between them without reading either schema.

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?

Names the alternative explicitly ('Use it where wait_for_selector cannot') and gives concrete triggering scenarios (a status line that changes, a spinner label that goes away). The when-to-use condition is stated rather than left to inference.

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