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

With no annotations, the description discloses critical behavioral traits: refs are pinned to snapshot elements, stale refs cause loud failures, refs invalidate on navigation, ref takes precedence over selector, fill clears first, and drag supports both element and pixel targets. This goes far beyond any structured metadata.

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 well-organized into sections: purpose, targeting methods, example flow, and action list. Every sentence earns its place, with clear bullet points and examples. It is long but appropriately so for 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?

Given the tool's 11 actions, no output schema, and no annotations, the description is remarkably complete. It covers targeting, all action nuances, failure modes, and the snapshot workflow, leaving no essential guidance for the agent.

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 schema lists fields with minimal descriptions, but the tool description adds rich semantics for each action: click's button options, drag's target vs offset modes, clicklink's text-based targeting, waitfor's timeout, and the 'ref wins' rule. This is far beyond schema basics.

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 clearly states it performs browser actions in sequence and batches multiple steps. It distinguishes itself from sibling tools by focusing on interactions like click, fill, drag, and keyboard presses, and explicitly references browser_snapshot for refs.

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?

It explicitly instructs to call browser_snapshot first to obtain refs and explains when to use selector vs ref. It also gives guidance on when to re-snapshot, though it does not explicitly contrast with alternative navigation/eval tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses detailed network entry structure, including auth-masked headers and duration_ms, which goes beyond a generic 'get debug info' description. However, it does not mention potential state impacts or whether console logs are cumulative, leaving minor gaps.

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 compact at about five sentences, with essential information front-loaded: it opens with 'PREFERRED DEBUGGING TOOL' and the rule to call before browser_screenshot. Each sentence adds value, and there is no redundancy or fluff.

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?

Despite the lack of an output schema, the description sufficiently explains the return values: URL, title, console logs, dialogs, and network request fields (method, URL, query params, headers, status, response body, duration). It also covers filter usage, making it complete for an agent to select and invoke 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?

The schema already describes all four parameters with 100% coverage, so the baseline is 3. The description adds contextual purpose for filters ('focus on specific API calls') and clarifies console_types usage, providing value beyond the schema without duplicating it.

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 explicitly identifies the tool as the 'PREFERRED DEBUGGING TOOL' and enumerates its return payload: current URL, page title, console logs, dialogs, and network requests. This distinguishes it from siblings like browser_screenshot and browser_navigate, making its purpose and scope clear.

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?

It states 'PREFERRED DEBUGGING TOOL' and 'Always call this before browser_screenshot,' providing explicit when-to-use and sequencing guidance. It also advises using specific filters to focus API calls, which is clear usage context.

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

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

With no annotations, the description carries the full burden and exceeds it: it details context recreation, cookie/localStorage preservation, IndexedDB loss, auto-navigation back, the innerWidth:980 fallback, and authoritative verification signals. Return value behavior and warnings are thoroughly explained.

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?

Though long, the description is well-structured with clear bullets and sections. The opening sentence is concise, and every bullet adds necessary behavioral or preset information. No fluff.

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, but the description explains return fields and verification semantics. No annotations exist, but the description covers all important edge cases (auth persistence, viewport fallback, error conditions). For a complex tool with nested custom parameters, this is complete.

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 baseline is 3. The description adds value beyond the schema by listing concrete viewport dimensions for each preset and reiterating custom requirements, making parameter selection easier.

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 opens with a specific verb and resource: 'Switch the browser session into a device emulation profile' and enumerates exact presets (iPhone, iPad, Android tablet, desktop reset, custom). It clearly distinguishes from siblings by noting persistence across browser_navigate and that browser_restart clears emulation.

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?

Explicit use cases are given: when to use device emulation, which preset to use for reset (desktop-chrome), and an exclusion ('Not supported in REAL_CHROME mode'). The persistence and auth behavior also inform when to use this tool versus browser_restart.

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

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

With no annotations, the description carries the full burden. It discloses that code is evaluated as an expression and recommends IIFE for multi-statement code, which is a valuable behavioral detail. It also provides examples showing side-effecting operations (dispatching events, appending text) but doesn't warn about potential page crashes or persistent state changes.

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 well-structured with a concise opening sentence followed by focused bulleted examples and a crucial closing note about IIFE usage. Every sentence and bullet contributes actionable information without unnecessary fluff.

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 one-parameter tool with no output schema, the description is remarkably complete. It covers what the tool does, when to use it, provides many usage examples, and explains evaluation semantics. The only minor gap is error handling, but the given context is sufficient for an agent to invoke 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?

Schema coverage is 100%, but the description adds enormous value by giving example code snippets that directly inform how to fill the 'code' parameter. It goes beyond the schema's basic description, making the parameter's possibilities and constraints much clearer.

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 clearly states 'Execute JavaScript in the page context and return the result,' which is a specific verb+resource definition. It further differentiates itself from siblings by calling itself the 'ESCAPE HATCH for anything the other tools don't cover,' making its unique role explicit.

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?

It explicitly says to use this tool when other tools don't cover a need, and provides a rich set of concrete use cases (computed styles, app state, drag-and-drop, etc.) that illustrate when it's appropriate. The guidance is clear even though alternatives aren't named individually.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the request inherits session/cookies, CORS constraints, the return contents (status, headers, parsed body), and that it appears in the browser_debug network log. This is substantial context, though it does not cover error handling, timeout behavior, or side effects of non-GET methods.

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 three sentences, front-loaded with the primary purpose, followed by key behavioral details. Every sentence adds value: purpose, session/CORS behavior, and return/logging info. No redundant words or repetition of schema content.

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?

Given the tool has 5 parameters, no output schema, and no annotations, the description covers the essential usage context: authentication, CORS, return value, and integration with the debug log. It does not elaborate on error conditions or partial success, but the schema fills in parameter defaults. Overall, it is sufficiently complete for selection and invocation.

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 input schema covers 100% of parameters with descriptive field descriptions (e.g., 'auto-JSON-encoded if object', 'Response parse mode'). The tool description does not add meaning beyond the schema's parameter descriptions, so it earns the baseline score of 3 for this dimension.

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 opens with 'Execute an authenticated fetch() request inside the page context,' which clearly states the action and target. It distinguishes itself from sibling tools like browser_navigate (navigation) and browser_eval (script evaluation) by specifying it is a fetch request, not a navigation or UI interaction.

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 provides clear context for usage: it inherits the page's cookies and session, making it appropriate for authenticated requests. It also notes same-origin works automatically and cross-origin requires CORS, giving a practical condition. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

With no annotations, the description should disclose side effects. It discloses the optional clearing of console/network logs, but does not mention whether navigation waits for page load or what happens on failure. Some behavioral context is provided but not exhaustive.

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?

Two sentences, front-loaded with the core action, followed by a concise optional parameter note. Every word earns its place, with no redundancy.

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 2-parameter tool with no output schema, the description covers the primary action and optional parameter. It lacks a note about asynchronous navigation behavior, but this is a minor gap given the sibling tools like browser_wait_for_url.

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 baseline is 3. The description adds semantic value by recommending when to use the clear_logs parameter, providing context beyond the schema's plain definitions.

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?

Describes a specific verb+resource: 'Navigate the browser to a URL'. Clearly distinguishes from sibling tools like browser_act and browser_snapshot, which have different purposes.

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?

Provides clear usage context: 'navigate to a URL' implies when to use it, and adds a specific recommendation for clear_logs ('recommended when starting a new task'). However, it does not explicitly mention alternatives or exclusions.

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

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

With no annotations, the description carries the burden. It discloses the risk of large result sets and suggests mitigation, which is useful. However, it doesn't explicitly state that it's a read-only operation or describe the exact return structure, though the schema covers defaults.

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?

Two sentences, front-loaded with the core purpose, no filler. Every sentence earns its place.

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?

The description covers purpose, usage, and a key tip, while the schema fully describes all parameters. Without an output schema, the description gives a sense of what to expect ('element state, text, visibility, values'). It's adequate for a 6-param tool with a detailed schema.

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 baseline is 3. The description adds brief context for visible_only and limit (avoid huge result sets), but doesn't add much beyond the schema.

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 clearly states the tool queries DOM elements by CSS selector, which is a specific verb+resource. It also explains use cases (check state, text, visibility, values) and contrasts with screenshots, though it doesn't explicitly name alternative tools like browser_eval or browser_snapshot.

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?

It gives clear context: use to check element state/text/visibility/values when a screenshot isn't needed. It also recommends using visible_only and limit for broad selectors, which is actionable guidance. However, it doesn't explicitly state when not to use it or name alternatives.

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

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

No annotations are provided, so the description carries the burden. It discloses the core behavior of closing and reopening the browser session and adds context about when that is appropriate. It does not detail side effects like session state loss, but the action is unmistakable and the use case is described.

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 three short, purposeful sentences with no filler. It front-loads the core action, then adds usage guidance and parameter context, earning a top score for efficiency.

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 tool with one optional parameter and no output schema, the description is largely complete: it explains the purpose, when to use it, and the optional URL behavior. A slight ambiguity remains around what happens after restart if no URL is given, but this is minor.

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 input schema already documents the single optional url parameter with a clear description. The tool description reinforces it ('Optionally navigate to a URL immediately after restart') but does not add new semantic detail beyond what the schema provides.

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 uses a specific verb-resource pair ('Close and reopen the browser session'), which clearly identifies the action and object. It also distinguishes itself from siblings by focusing on recovery from dead, crashed, or stuck pages rather than navigation or 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 explicitly states when to use the tool ('when the page is dead, crashed, or stuck after navigating to an external site') and mentions the optional navigation after restart. It does not explicitly list alternatives or when-not-to-use, but the context is clear.

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

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

With no annotations, the description must disclose behavioral traits itself. It does: 'Expensive and unstructured' warns about cost and output format. It could further note that it captures the current viewport (though the schema covers this via quality options), so a slight gap remains.

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?

Four short sentences, all essential: a warning, the core function, a usage condition, and an alternative directive. Front-loaded with 'LAST RESORT' to prevent misuse. No wasted words.

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?

The tool is simple (one optional param, no output schema), and the description covers its purpose, usage constraints, cost, and output format. The qualitative alternatives are explicitly named. This is complete for the tool's complexity.

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 schema covers the single 'quality' parameter 100% with detailed enum descriptions. The description adds no information about parameters, so 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?

The description clearly states the tool's function: 'Returns a screenshot as base64.' This is a specific verb and resource, and the explicit 'LAST RESORT' framing distinguishes it from sibling tools like browser_debug or browser_query.

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?

It provides explicit when-to-use guidance ('Only use when the problem is purely visual') and when-not-to-use by naming alternatives ('Always try browser_debug and browser_query first'). This is exactly the kind of exclusionary context needed.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds useful context about scrolling within containers versus the page, and mentions scrolling elements into view. However, it does not disclose potential side effects (e.g., whether scrolling is instant or smooth), precedence if multiple parameters are provided, or any limitations. The description is functional but not deeply transparent about edge-case 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 two sentences long and front-loaded with the primary action. Each sentence serves a purpose: the first enumerates the three scroll modes, the second explains when to use the container parameter. There is no wasted or redundant 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?

Given 4 optional parameters and no output schema, the description covers the three main use cases (page, container, element) well. It does not explain interactions between parameters (e.g., what happens if selector and container are both set), but the schema already describes individual parameter overrides. The description is sufficient for a browser scrolling tool, though a note about parameter precedence would make it more complete.

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 baseline is 3. The description adds value by clarifying the intended use of the 'container' parameter ('scroll inside scrollable divs instead of the page') and contextualizing the 'selector' parameter as 'scroll an element into view'. This enriches the schema's descriptions with real-world scenarios, particularly for container scrolling.

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 clearly states the tool's function with a specific verb ('scroll') and resource distinctions: page, container element (with examples), and element into view. It differentiates from sibling tools like browser_navigate and browser_act by focusing solely on scrolling behaviors. The scope is unambiguous and well-defined.

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 says 'Use 'container' to scroll inside scrollable divs instead of the page,' giving clear guidance on when to use the container parameter. It does not explicitly name alternative tools like browser_eval for scrolling, but as the dedicated scroll tool, the appropriate context is implied. There is no exclusionary guidance, but the container-vs-page distinction provides actionable usage direction.

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

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

With no annotations, the description carries the full burden and delivers. It discloses the return format, that refs map internally to stable selectors, that they invalidate on navigation, and that testId is included when present. It also explains the effect of compact:true on the tree. This is rich behavioral context.

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 structured with a clear purpose, return type, usage example, and edge-case notes (ref invalidation, compact). It is front-loaded with the key action and uses concise bullet-like prose; every sentence adds distinct value.

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?

As there is no output schema, the description must and does explain the return shape, ref semantics, and the recommended companion tool (browser_act). It also covers navigation invalidation and parameter behavior, making it complete for a tool of this complexity.

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% with both compact and max_depth described. The description adds practical guidance for compact—'to drop pure layout wrappers (divs/spans with no role, no testId)' and 'Recommended for noisy apps with deeply-nested div soup'—extending beyond the schema's descriptor. max_depth remains schema-only, but the additional compact context justifies a score above baseline.

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 opens with 'Return the accessibility tree of the current page with refs attached to interactive elements,' a specific verb+resource that clearly states what the tool does. It also differentiates from siblings by explicitly advising to use it INSTEAD of guessing CSS selectors from a screenshot, distinguishing it from browser_screenshot.

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?

Explicitly states 'Use this INSTEAD of guessing CSS selectors from a screenshot' and explains that refs are stable while selectors break on class-name churn. It also instructs to pass refs to browser_act and notes that refs invalidate after navigation, providing clear when-to-use context. This is explicit guidance beyond simple purpose.

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

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

No annotations are provided, so the description must disclose behavior. It mentions multiple file support and absolute path requirements, adding useful context. However, it does not discuss side effects, error behavior, or whether the upload replaces existing files, leaving gaps.

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 two sentences, front-loaded with the main action and clear instructions. Every word earns its place.

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 two-parameter tool with no output schema, the description covers the essential usage. It could mention expected return values or asynchronous behavior, but it is generally complete for the tool's purpose.

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 covers both parameters with descriptions, and the description reinforces the selector and file paths. It adds the 'absolute file paths' requirement and 'one or more files' context, which goes slightly beyond the schema. This provides added semantic value.

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 clearly states the tool uploads files to a file input element, using a CSS selector and absolute file paths. This distinguishes it from sibling tools like browser_navigate and browser_act, as it specifically targets file uploads.

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 clear context: use when you need to upload files to a file input element. It instructs to use a CSS selector and provide absolute paths, but does not explicitly mention when not to use it or alternatives. This is solid but lacks explicit exclusions.

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

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

With no annotations, the description carries the full burden. It discloses the any-of matching behavior for url_pattern, timeout default, and the return value (status and JSON body). It doesn't mention timeout error behavior, but the disclosed details are sufficient for a read-like 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 two sentences, front-loaded with the main purpose, then elaborates usage and parameter behavior. Every sentence earns its place with no redundancy or fluff.

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?

Given three simple parameters, no output schema, and no annotations, the description covers purpose, usage, return value, and parameter semantics. It could mention error behavior on timeout, but for a straightforward wait tool, the coverage is solid.

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 baseline is 3. The description adds value beyond the schema by explaining the any-of match semantics for url_pattern arrays and confirming the timeout default, which the schema only lists without these nuances.

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 clearly states the tool waits for a network response matching URL pattern and/or method, and returns the response with status and JSON body. This specific verb+resource distinguishes it from sibling tools like browser_wait_for_url, which waits for URL navigation.

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?

It explicitly says to use after triggering an action 'instead of guessing with wait times', providing clear use context. It doesn't name alternative sibling tools explicitly, but the guidance is actionable and distinguishes from generic waiting.

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

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

With no annotations, the description carries the full burden. It discloses key behaviors: waits for URL change, matches substring, returns current URL on timeout (non-throwing), and optionally chains a readiness gate. It could be more explicit about whether it succeeds immediately if the URL already matches, but this is a minor gap given the usage context.

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?

Four sentences, no redundant wording. Front-loaded with the core action, then usage context, timeout behavior, and optional chaining. Every sentence adds value, making it concise and well-structured.

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?

The description covers the essential aspects for correct usage: what it does, when to use it, timeout behavior, and optional chaining. No output schema exists, so it doesn't need to explain return values, but it does mention the timeout return. It doesn't explicitly explain what happens on success (likely no return value), but that is a minor omission for a wait operation.

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% for all 4 parameters, so the baseline is 3. The description adds some contextual meaning to wait_for (readiness gate, avoiding follow-up), but doesn't add syntax or details beyond what the schema already provides for pattern, exact, timeout, and wait_for.

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 uses a specific verb ('Wait') and resource ('page URL'), and clearly states the action: 'wait for the page URL to change and match a substring pattern.' It distinguishes itself from sibling tools like browser_wait_for_network by focusing on URL changes rather than network idle.

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?

Explicitly states when to use: 'Use after actions that trigger redirects (JS redirects, auth redirects, SPA route changes).' This provides clear context and indicates it is a follow-up wait operation. It also suggests an alternative pattern ('so you don't have to follow up with setTimeout/wait') for chaining with wait_for, showing awareness of alternatives.

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