agent-browser-mcp

Overview Schema Source Related Servers Discussions Admin

wait_for

Destructive

Wait for a selector, text, URL pattern, or JavaScript expression to become true on the page, then return. Avoids polling and repeated DOM serialization.

Instructions

Wait until a condition holds on the page, then return. Use this instead of polling scan_page (each scan re-serializes the whole DOM). Exactly one of selector / text / url_pattern / js must be given: selector waits for a CSS or structured-locator match, including nested same-origin/cross-origin iframe paths. Role locators exclude hidden and inert controls; disabled visible controls can still be observed. Text waits for a substring in body text, url_pattern for a regex on the URL, js for a JS expression to become truthy. Caller js is evaluated repeatedly and can have side effects; use a read-only predicate. The server schedules short synchronous page checks under one deadline. A delayed reply returns its operation_id for get_execute_js_result; it is never replayed while pending. Timed-out top-document selector/text/URL checks can release the tab while keeping that receipt: reservation_held=false permits another command. Framed checks and caller-provided js may stay reserved; when reservation_held is true or unknown, collect the original operation first.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "wait_for"
  }
}

Input Schema

Name	Required	Description	Default
`js`	No
`gone`	No
`text`	No
`timeout`	No
`selector`	No
`session_id`	No
`url_pattern`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 5, 2026

TDQS

A4.6/5.0

Behavior5/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

Deploy Server