wait_for

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

The description goes well beyond the annotations by disclosing that caller js is evaluated repeatedly and may have side effects, that a delayed reply returns an operation_id for get_execute_js_result, that pending operations are never replayed, and that timed-out top-document checks can release the tab while keeping a receipt. It also explains reservation_held semantics and how to handle framed checks and caller-provided js. This is exemplary behavioral disclosure for a tool with subtle asynchronous and reservation behavior.

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 long but every sentence delivers distinct, necessary information: purpose, alternative, mode rules, JS caveats, scheduling, operation_id, reservation behavior, and fallback instructions. It is front-loaded with the core purpose and usage, then progressively covers edge cases, so the length is justified by the tool's complexity.

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 complex asynchronous wait tool, the description is remarkably complete: it covers condition modes, alternatives, side effects, delayed replies, deadlines, and tab-reservation behavior. The main gap is the unexplained 'gone' parameter and the lack of any mention of timeout/session_id, though output schema and parameter names partially mitigate those. Overall, an agent has nearly everything needed to use the tool correctly.

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?

With schema description coverage at 0%, the description must compensate. It thoroughly explains selector, text, url_pattern, and js, including structured-locator behavior and side-effect warnings. However, it omits the 'gone' parameter, which is non-obvious from the schema alone and central to absence-based waits, and it does not clarify timeout or session_id semantics. The description covers the core modes but leaves meaningful parameter gaps.

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 starts with a specific verb and resource: 'Wait until a condition holds on the page, then return.' It clearly differentiates itself from scan_page by saying 'Use this instead of polling scan_page (each scan re-serializes the whole DOM),' and it enumerates the exact condition modes (selector, text, url_pattern, js). An agent can immediately know what this tool does and how it differs from a key sibling.

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 explicitly names the alternative, scan_page, and gives the reason to prefer wait_for: 'Use this instead of polling scan_page.' It also states the mandatory usage rule 'Exactly one of selector / text / url_pattern / js must be given' and describes what each mode waits for, which is strong actionable guidance for an agent deciding to call this tool.

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