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 input mechanism (trusted events), the return value (updated snapshot), and a genuinely valuable prompt-injection warning about untrusted page content. However it says nothing about the consequences of the click itself (possible navigation, writes, or irreversible actions) or failure behavior, which matters for a clicking tool.

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 compact sentences, front-loaded with the core action and targeting options, ending with the safety note. Every sentence conveys distinct information with no padding.

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 an 8-parameter tool with no output schema and no annotations, the description covers targeting, click variants, modifiers, and the return value, which is most of what an agent needs. It is only slightly thin on post-click side effects and error handling.

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 75%, and the description usefully names the concepts behind the two undocumented params: right/middle click maps to 'button' and 'double click' maps to 'doubleClick'. It also reinforces the ref vs x/y distinction and notes the snapshot return. It adds real meaning 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?

States a specific verb (click) plus the two targeting modes (element ref or x/y), and clarifies it uses real trusted mouse input. This cleanly separates it from browser_hover, but it never names a sibling explicitly, which is why it falls short of 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?

Gives clear context on the two invocation paths ('an element ref from the snapshot, or x/y from a screenshot'), which helps the agent choose how to target. It stops short of stating exclusions or when-not-to-use conditions.

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 behavioral burden. It contributes one genuinely valuable trait — that page content is untrusted and instructions in it must be ignored — but is silent on whether reads are cumulative or clear the buffer, how results relate to lastSeq, and whether errors and messages are interleaved or separated.

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 short sentences, both front-loaded and earning their place: the first states what is returned, the second delivers a security constraint. No filler or 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?

With no output schema and no annotations, the description must stand alone. It adequately conveys what comes back for a simple read tool, but leaves the undefined 'limit' parameter and the pagination model unexplained, which an agent needs to poll console output 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 only 50%: 'limit' has no description at all, and 'since' references a 'lastSeq' value that is never defined. The description mentions no parameters whatsoever, so it does not compensate for the documentation 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 names a specific resource — console messages and uncaught errors — and scopes it to 'the shared page', which distinguishes it from siblings like browser_network and browser_evaluate. It lacks an explicit verb ('Retrieve'/'List'), but the returned content is unambiguous, so an agent can identify it without opening the 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?

There is no when-to-use guidance: no statement of when to reach for browser_console versus browser_network (which likely also surfaces errors) or browser_evaluate. No prerequisites or exclusions are given, leaving usage entirely to inference.

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 load and does well: it discloses a known limitation (HTML5 drag may not respond), the return behavior (updated page snapshot), and a security caveat about untrusted page content. It does not cover permissions or failure/rollback semantics, so not a 5.

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 dense sentences, front-loaded with the action, followed by the caveat and the return/security note. No filler.

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 an 8-parameter tool with no output schema and no annotations, the description covers action, return value, and security context. The main gap is not clarifying how the coordinate parameters interact with the ref parameters, but overall it is sufficient to 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?

Schema coverage is only 25% on 8 parameters, so the description should compensate more than it does. 'One element/point, move to another' hints at the fromRef/toRef vs fromX/fromY duality, but the coordinate-vs-reference relationship is never made explicit.

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 precise verb sequence (press, move, release) on a clear resource, and names concrete use cases (sliders, sortable lists, canvas) that separate it from browser_click and browser_hover. An agent can tell immediately what this does.

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 parenthetical use cases and the warning that 'Native HTML5 drag-and-drop may not respond' give real context for when this tool applies versus a plain click or hover. It stops short of explicitly naming an alternative tool or stating exclusion conditions, so not a 5.

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 does disclose the gating configuration (haiBrowser.allowEvaluate) and the JSON return contract, which is useful. It omits major behavioral traits: arbitrary JS can mutate page state, there is no statement about timeouts, waiting for the page to settle, or error propagation on a throwing expression.

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 short sentences, no filler, with the core action front-loaded and the precondition second. Every clause 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 code-execution tool with no annotations and no output schema, the description covers the action and the enablement gate but leaves the agent guessing about side effects, timeouts, and error behavior. Adequate but with clear gaps given the risk profile of arbitrary evaluation.

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 0% and the single required 'expression' parameter is undocumented in the schema. The description adds only that the expression is JavaScript and that its value is returned as JSON — mildly useful, but it does not clarify evaluation scope, serialization limits, or whether async/promise expressions are awaited.

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 verb ('Run') and resource ('JavaScript expression in the shared page') plus the return shape (its JSON value). It is clearly distinguishable from read-only siblings like browser_console or browser_snapshot, though it never names an alternative explicitly.

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 a real precondition — the tool is disabled unless the user enables haiBrowser.allowEvaluate — which tells the agent when the call will fail. It gives no guidance on when to prefer this over sibling tools such as browser_console or browser_snapshot for inspecting page state.

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 does so well: it discloses that wait=true blocks until the user clicks or presses Esc, that source file:line is only available when the app uses the hai-browser-vite plugin, and it warns that page content is untrusted and must not be followed as instructions. These are non-obvious behavioral traits beyond any structured field.

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 first sentence front-loads the return payload as a compact list, followed by trigger guidance, the wait semantics, and the security warning. Dense and mostly waste-free, though the long enumeration in sentence one could be trimmed for readability.

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 full return payload and its conditions. Combined with the blocking behavior, plugin dependency, and untrusted-content caveat, an agent has everything needed to invoke and interpret this 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 already 100%, so the baseline is 3, but the description adds meaning the schema lacks: wait=true is a blocking picker that ends on click or Esc. It does not restate the timeoutSeconds default of 300, so it is slightly above baseline rather than exhaustive.

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 verb and resource ('Get the element the user picked in the shared tab') and enumerates exactly what it returns: source file:line, selector, text, HTML, computed styles, a ref, and a screenshot. It is clearly distinguishable from siblings like browser_snapshot or browser_click because it explicitly says the ref it returns feeds browser_click/browser_type/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?

Gives a concrete trigger condition: 'Use it when the user says "this"/"that element"', and explains that wait=true asks the user to pick now. It does not name an alternative tool or state when NOT to use it (e.g., versus browser_snapshot for whole-page inspection), so it stops short of explicit routing.

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 behavioral burden and does reasonably well: it discloses that accepting/dismissing is the effect, that the updated page snapshot is returned, and adds an untrusted-content safety caveat. It omits what happens if no dialog is open (error vs no-op) and whether prompt input is required, keeping it short of a 5.

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 tight sentences, front-loaded with the primary action, followed by behavioral note and safety caveat. No filler and every sentence contributes information.

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 no output schema and no annotations, the description covers the action, the return (updated snapshot), and the key safety framing. It stops short of describing error behavior when no dialog exists or how promptText interacts with accept=false, but it is otherwise adequate for a 4-param tool.

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 the schema already documents 'accept' (true=OK/false=Cancel), 'snapshot', 'promptText', and 'screenshot' clearly. The description adds no syntax or conditional detail beyond that, so the baseline of 3 applies.

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 verb pair (accept or dismiss) plus the exact resource class (alert/confirm/prompt dialog), which cleanly differentiates it from generic input siblings like browser_press_key and browser_type. An agent can identify the operation immediately.

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 phrase 'the open ... dialog' and 'Actions report when one is open' implies this tool is used only when a dialog is present, giving implied triggering context. However, there is no explicit statement of when-not-to-use or which sibling to reach for otherwise, leaving routing to inference.

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 behavioral burden. It does disclose the return value ('Returns the updated page snapshot') and a genuine safety caveat about untrusted page content, which is valuable. However, it omits side-effect detail such as whether hovering triggers JS/timing-dependent UI, and how hover state interacts with subsequent actions.

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 compact sentences, front-loaded with the action, then the return value, then the safety note. No filler and every sentence contributes distinct information.

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 pointer action with five optional parameters, no required params, and no output schema, the description adequately covers purpose, return behavior, and the untrusted-content caveat. Minor gaps remain around timing/side effects, but nothing essential to invoking it correctly is missing.

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 the schema already documents x, y, ref, snapshot, and screenshot, including defaults. The description adds only the ref-vs-coordinate alternative, which is already conveyed by the schema, so the 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 names a specific verb ('move the mouse over') and both targeting mechanisms ('element ref or x/y point'), with a concrete example outcome (hover menu or tooltip). It is clearly distinguishable from sibling actions like browser_click or browser_drag by the verb itself, though it never explicitly names a sibling to contrast against.

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 example 'e.g. to open a hover menu or tooltip' implies the intended usage scenario, but there is no explicit when-to-use vs when-not guidance and no alternatives named (e.g. use browser_click if you also need to activate the element). Usage is inferred rather than stated.

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 disclosure burden. It hints that it operates on a 'shared tab' but does not say whether navigation blocks until load completes, how it interacts with existing page state, or what happens on failure.

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?

A single compact sentence that front-loads the primary use case (URL) before the secondary modes. No wasted words, though the brevity contributes to the underspecification elsewhere.

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?

With no annotations and no output schema, the description should do more. It covers the surface actions but leaves unanswered how this differs from sibling navigation tools and how the two parameters interact, which an agent needs to call it 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 0%, so the description must compensate. It does name the URL target and the three enum actions, which map onto both parameters, but it omits any detail on URL format and never clarifies the mutual exclusivity or precedence between url and action.

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 gives a specific verb (navigate) plus resource (the shared tab) and enumerates the three non-URL modes (back, forward, reload). This is clear and distinct from most siblings, though it never contrasts itself with similar navigation-related tools like browser_open or browser_tab_new.

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 what navigation actions exist but offers no guidance on when to reach for this tool versus alternatives such as browser_open or browser_tab_new. The choice between moving the current tab and opening a new one is left entirely to inference.

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 adds genuinely useful behavioral/safety context by warning that page content is untrusted and must not be followed, but it says nothing about read-only nature, how requests accumulate, freshness, or pagination via since.

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 tight sentences, front-loaded with the resource and returned fields, followed by the safety note. No filler, and 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?

With no output schema and no annotations, the description partially compensates by enumerating returned fields and flagging untrusted content. However, it leaves limit undocumented and doesn't clarify result shape or pagination behavior for a data-retrieval tool.

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 67%: since and filter are documented in the schema, but limit is not. The description adds no parameter meaning at all, so the undocumented limit remains unexplained. With most params covered by the schema, the baseline of 3 fits.

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 names a specific resource (network requests) and enumerates the returned fields (method, URL, status, type, duration, size), so an agent can distinguish it from siblings like browser_console or browser_screenshot. It lacks explicit sibling routing, but the purpose is unambiguous.

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?

There is no when-to-use guidance, no prerequisites, and no named alternatives among the ~20 browser siblings. The only guidance is a security caveat, not 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 it does disclose one meaningful trait: it targets a browser the user is watching and opens a new tab if none is shared. It omits whether this is headless or visible, whether it waits for load, and what happens on failure, which matters for an operation with side effects in a shared session.

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 tight sentences, front-loaded with the action and scoping, followed by the alternative-selection rule and the tab fallback. No filler.

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 navigation tool with no output schema, the description covers the essentials plus the shared-session and new-tab behavior. It falls short only on distinguishing itself from the near-identical browser_navigate sibling.

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% and there is a single required parameter, so the schema already documents the URL format. The description's 'website or localhost app' adds only a mild hint about accepted targets, so the baseline of 3 applies.

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 verb and resource ('Open a URL ... in the browser inside VS Code') and clarifies scope with 'website or localhost app'. It does not, however, differentiate itself from the very similarly named sibling browser_navigate, which is the reader's most likely confusion.

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 gives a use condition ('whenever the user wants a page opened, viewed, tested, or clicked through') and names an alternative (WebFetch) to prefer this over. The gap is that the closest sibling, browser_navigate, is never addressed, so sibling selection remains ambiguous.

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 it does disclose two useful traits: the return of an updated page snapshot and a security posture warning about untrusted page content. It omits prerequisites such as whether the page/element must be focused, what happens on invalid key names, and whether the snapshot default can be disabled.

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 tight sentences, front-loaded with the action and input formats, followed by an output note and the safety warning. Every clause earns its place with no filler.

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 annotations and no output schema, so the description is the main carrier; it covers action, input formats, and return value. Minor gaps remain around focus prerequisites and failure behavior for a browser-interaction tool.

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 67%, and the undocumented 'key' parameter is exactly where the description adds value: named keys, plain characters, and chord syntax (Control+A, Shift+Tab). The snapshot/screenshot booleans are already documented in the schema, so no repetition is needed.

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?

Specific verb (Press) plus resource (a key or shortcut in the page) with concrete key examples (Enter, Escape, Tab, chords like Control+A). An agent immediately knows what the tool does, though it never contrasts itself with the overlapping sibling browser_type for single characters.

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 key examples imply the input domain but there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g., versus browser_type, browser_click, or browser_handle_dialog for Escape on a dialog). Usage must be inferred.

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, and it delivers two meaningful behavioral facts: the operation blocks until the user chooses, and it preserves cookies/sign-in (avoiding re-authentication). It omits what happens on decline/timeout, which a blocking tool should clarify.

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?

A single front-loaded sentence with no waste. The parenthetical efficiently packs in the credential-preservation nuance without a second sentence.

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 zero-parameter tool with no output schema, the description covers purpose, blocking behavior, and credential handling well. The main gap is what it returns (a tab identifier/handle) and the outcome if the user declines, which an agent would need to handle the result.

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 tool takes zero parameters, so the baseline is 4. There is nothing for the schema to describe and nothing the description needs to compensate 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?

States a specific action (ask the user to pick an open integrated-browser tab to share) with the key effect (keeps cookies and sign-in). This is clearly distinguishable from all sibling browser_* tools, which act on the page rather than requesting user collaboration.

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 implies when this applies (when you need a tab the user is already signed into), but never states when to prefer it over alternatives like browser_open or browser_navigate, nor any exclusions. Usage is inferred rather than spelled out.

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 disclosure burden. It does disclose real behavioral facts: viewport is the default mode, images are in CSS pixels, and annotate=true returns a matching snapshot in addition to the image. It is silent on whether the image is returned inline or written to a file, and on any size/rate limits, leaving notable gaps for an unannotated tool.

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 tightly written sentences, front-loaded with the core action and mode enumeration, followed by coordinate interop and annotation behavior. No sentence is redundant and no filler is present.

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?

With no annotations and no output schema, the description does well: it explains capture modes, coordinate semantics, and the annotate return behavior. The remaining gap is the return transport (inline image vs. file path) and any limits on capture size, which an agent would still have to discover.

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 only 67% (fullPage has no schema description), and the description compensates by explaining each parameter's effect: ref selects one element, fullPage selects the whole page, and viewport is the default. It also adds the non-obvious constraint that annotate is viewport-only, which the schema does state but the description reinforces with the return-value behavior.

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+resource ('Screenshot the shared tab') and immediately enumerates the three capture modes: viewport (default), one element, or full page. An agent can distinguish this from siblings like browser_snapshot or browser_evaluate without opening the 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?

It gives a genuinely useful usage rule for the viewport mode (CSS-pixel coordinates work directly with browser_click/browser_hover) and tells when to set annotate=true. However, it never states when to prefer browser_snapshot or browser_evaluate over taking a screenshot, so the choice among visual-capture siblings is left to inference.

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 does deliver: it states the return value (updated page snapshot) and adds a prompt-injection safety warning about untrusted web content. It omits whether scrolling is viewport-only or persistent, and what happens with a stale ref, but the safety disclosure and return-value statement are meaningful context beyond the schema.

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 tight sentences, front-loaded with the core action and modes, then the return value and safety note. Zero filler and nothing buried.

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 7-parameter, all-optional tool with no output schema, the description covers modes, return value, and the untrusted-data caveat, which is close to sufficient. Minor gaps remain (stale-ref behavior, interaction of snapshot=false with other steps), keeping it just under a 5.

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 every parameter (x, y, ref, deltaX, deltaY, snapshot, screenshot) is already documented in the schema. The description reinforces the ref/x/y mode relationship but adds no syntax or format detail beyond what the schema provides; baseline 3 applies.

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 verb (Scroll) and enumerates the distinct modes: at an element ref, at an x/y point, at the viewport middle, or ref-only to scroll into view. An agent can immediately distinguish this from sibling read tools like browser_snapshot or browser_screenshot without opening any 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?

The description explains which input combination triggers which behavior (ref vs x/y vs default viewport center, and ref-only for scroll-into-view), which is genuine when-to-use guidance for this tool. It does not, however, contrast against alternatives such as browser_navigate or when scrolling is unnecessary, so it stops short of 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 two traits beyond the schema: the operation returns an updated page snapshot, and page content is untrusted so instructions in it must not be followed (a genuinely valuable safety note). It does not cover failure behavior on a missing/ambiguous option, event dispatch, or multi-select semantics, so it is adequate but incomplete.

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 earning its place: the action, the return value, and the injection guard. The core verb and target are front-loaded with zero filler.

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?

With no output schema and no annotations, the description supplies the return-value expectation and the untrusted-data warning, which is most of what an agent needs. It falls short only on the meaning/source of `ref` and on error handling for invalid or ambiguous option matches.

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 50%, so the description must compensate. It usefully clarifies that `values` accepts option values OR visible labels, which the schema's bare string array does not convey. However, `ref` is left completely undefined in both the schema and the description, and the snapshot/screenshot flags are only documented in 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?

States a specific verb (Choose) and resource (option(s) in a <select>) plus the two accepted identifier forms (value or visible label). This is clearly distinguishable from siblings like browser_click, browser_type, and browser_press_key without opening any 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?

The phrase 'in a <select>' implicitly scopes usage to dropdown elements, which is useful routing context, but the description never states when to use this instead of alternatives (e.g. browser_click on a native picker) or any prerequisites such as needing a ref from a prior snapshot.

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, and it does well: it discloses the visible side effects (scrolling, cursor movement, temporary highlight), the return value ('the highlighted text with its context'), and a security caveat about untrusted page content. It does not say what happens when the text is not found or how ref and text interact, leaving a small gap.

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 action and followed by the decision rule and safety note. Every clause — including the untrusted-content warning — 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 five-parameter, zero-required visual tool with no output schema, the description covers action, trigger, output shape and a security caveat. Only the failure case (no match found) is unaddressed, which an agent would likely encounter.

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 ref, text, label, snapshot and screenshot are already documented. The description only echoes the optional caption and the highlight target, adding no format or precedence guidance (e.g. which of ref vs text wins). 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 verb+resource ('Show the user something on the page') plus the concrete mechanics: scroll into view, move the visible cursor, highlight, optional caption. This clearly separates it from browser_screenshot and browser_snapshot, which capture rather than annotate the page for the user.

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?

Gives an explicit trigger condition — 'Call it before you use a value you read on the page' — with four concrete examples (verification code, link, price, error message) and the reason ('the user cannot see what you read from snapshots'), which implicitly contrasts it with the snapshot siblings.

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 behavioral burden and does so: ref stability across page presence, iframe ref naming (f1e3), read-only sandboxed srcdoc frames, paginated parts with offset handoff, and an untrusted-content warning against following in-page instructions. These are non-obvious traits an agent cannot infer from structured fields.

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?

Purpose is front-loaded in the first clause, then details (refs, iframes, pagination, safety) follow in a compact sequence. Every sentence carries a distinct operational fact; none is filler.

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?

There is no output schema, so the description must convey the return shape, which it does (outline with refs, inline iframes, paginated parts plus trailing offset). Combined with the untrusted-data caveat, an agent has everything needed to call and interpret this 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% and the single parameter is already documented, so the baseline is 3. The description adds genuine value by explaining the offset originates from the end of the previous part and drives continuation paging, tying the parameter to a workflow rather than just a type.

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 verb and resource ('Read the shared page as an accessibility-style outline') and clarifies it is a text-structure read, distinguishing it from browser_screenshot, browser_console and browser_network without needing the schema. The [ref=eN] detail makes the output identity unmistakable.

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?

Strong implicit routing: refs are 'for use with the other browser_* tools', and sandboxed srcdoc frames must have their links opened with browser_navigate instead of through snapshot. It doesn't explicitly contrast snapshot vs screenshot/console when choosing what to inspect, so it falls short of a full when/when-not matrix.

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 does disclose the return content (share state, URL, title), which is valuable given there is no output schema, but it says nothing about side effects, whether the browser must already be open, or what an unshared/absent result looks like.

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?

A single tight sentence with no filler, and the key payload (share state, URL, title) is stated up front. It is appropriately sized for a zero-argument status check.

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?

With no output schema, the description does the minimum by listing the returned fields, and for a trivial 0-param status query that is close to sufficient. It still omits the conditions under which a tab is considered 'shared' and what the agent should do with the result, so it is adequate but not 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level gaps exist.

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 states the resource (VS Code integrated-browser tab) and the information returned (shared status, URL, title), so an agent can infer it is a state query. However, it is phrased as a noun clause rather than a verb+resource action, and it never contrasts itself with the closely related browser_tabs sibling, leaving the boundary ambiguous.

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?

There is no statement of when to call this versus browser_tabs, browser_snapshot, or any other sibling, and no prerequisites or exclusions. The agent must infer usage entirely from the name and the returned-data clause.

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 behavioral burden. 'Shared tab' hints at a shared browsing context but the description never says whether closing destroys state, whether it affects other clients sharing the tab, what happens to the active tab pointer afterward, or how an invalid/absent id is handled.

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?

A single short sentence with the default behavior front-loaded in parentheses; nothing is wasted. It is terse to the point of under-specification, but brevity itself is handled well.

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-optional-parameter tool this is roughly the minimum viable, but with no output schema and no annotations the description leaves return behavior, failure modes, and destructive impact of closing a shared tab unexplained.

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 0% for the single 'id' parameter, so the description must compensate. It does add one meaningful fact — omitting id closes the active tab — which the schema alone does not convey, but it says nothing about accepted id formats or what happens if the id is stale or unknown.

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 verb (close) and resource (shared tab), which cleanly separates it from siblings like browser_tab_new and browser_tab_select. It does not explicitly name those siblings or describe scope beyond 'shared tab', so differentiation is inferable rather than stated.

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?

There is no guidance on when to close a tab, prerequisites, or what to do instead (browser_tabs, browser_tab_select). The only usage-relevant detail is the default-target note, which is about the parameter rather than about selecting this tool over 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?

With no annotations, the description carries the full behavioral burden. It discloses the key state change (the new tab becomes active), which is genuinely useful, but omits session prerequisites, error behavior, and whether a tab identifier is returned.

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?

A single, front-loaded sentence with the action first and the side effect second; no filler or 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 one-parameter tool with no output schema this is adequate, but it leaves open prerequisites for calling it and what the caller gets back, so it is minimally viable rather than 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 description coverage is 0% for the single 'url' parameter, so the description must compensate and largely does not. It implies the argument is a URL but says nothing about required format, scheme, or whether relative/absolute URLs are accepted.

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 states a clear verb ('Open') and resource ('a URL in a new integrated-browser tab'), plus the immediate side effect of making it active. This implicitly separates it from browser_navigate (current tab) and browser_tab_select, though it never names those siblings explicitly.

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?

There is no explicit guidance about when to open a new tab versus navigating the current one, no prerequisites (must a browser session already exist?), and no named alternative such as browser_navigate. The 'new tab' phrasing hints at a distinction but the agent must infer it from the tool name rather than the description.

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 does add useful behavior beyond the name by disclosing that only shared tabs are listed, that actions target the active tab, and that unshared tabs are reported only as a count. It does not state that it is read-only, nor describe the return shape or ordering.

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?

A single dense sentence with no filler, front-loading the primary action (listing shared tabs). The parenthetical is slightly awkward but earns its place by clarifying active-tab semantics.

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 no-parameter, no-output-schema listing tool, the description covers both halves of the result (shared tabs and the count of unshared ones) plus the active-tab targeting rule. It is nearly complete, with only the absence of explicit read-only confirmation as a minor gap.

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 tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to compensate for on the parameter side.

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 verb (list) and resource (integrated-browser tabs shared with you), plus a second output component (count of unshared VS Code browser tabs). This clearly differentiates it from the action-oriented siblings like browser_tab_select, browser_tab_close, and browser_tab_new, though it never names them.

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?

Usage is only implied: the agent can infer it should call this to discover available tabs. The parenthetical 'actions go to the active one' hints at the relationship with the tab-targeting siblings but does not explicitly say when to use this versus browser_tab_select or browser_status.

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 does disclose one important behavioral trait beyond the schema — that the selection is global and affects all browser_* tools — but says nothing about error behavior for an unknown/invalid id, whether the tab must already be shared, or whether the selection persists across sessions.

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?

A single sentence with zero filler, front-loaded with the action and followed by the qualifying scope. Nothing to 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?

For a one-parameter, no-output-schema tool the description covers the essentials (what it does, where the id comes from, what it affects). It stops short on the failure mode for an invalid id and on the prerequisite that a tab must be shared/open, which an agent would want for a state-mutating selection tool with no annotations.

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 0% and the single 'id' property has no description, so the description must compensate. It does add real meaning by telling the agent the id comes from browser_tabs, which is the one thing the bare schema cannot convey.

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 gives a specific verb+resource ('make a shared tab the active tab') and states the scope of effect ('for all browser_* tools'). It also points at browser_tabs as the source of the id, but it never explicitly distinguishes itself from the closest siblings browser_tab_new / browser_tab_close / browser_tabs.

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?

Usage is implied rather than stated: an agent can infer you call this to activate an existing tab before using other browser_* tools, and that the id must come from browser_tabs. There is no explicit when-to-use / when-not guidance or any prerequisite about the tab being shared first.

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 usefully discloses that the action returns an updated snapshot and adds a security warning about untrusted page content (valuable prompt-injection guidance), but says nothing about failure modes when the ref is stale/missing, whether typing waits for the page, or what clear/submit do behaviorally.

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 efficient sentences: the action and return value are front-loaded, and the trailing safety warning earns its place for a tool that ingests arbitrary web page content. No filler.

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?

With no output schema, the description correctly states the return value (updated page snapshot) and covers the security caveat. It is slightly thin on mutation behavior (event dispatch, error/retry behavior) for a tool with six parameters and no annotations, but the core needs are met.

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 67%, with clear/submit/snapshot/screenshot already documented in the schema. The description reinforces ref's origin ('from the snapshot') and the snapshot return, but adds no syntax or format detail beyond the schema, so the baseline of 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 verb (type) plus the resource (an element identified by ref from the page snapshot), which cleanly separates it from siblings like browser_press_key and browser_select_option. An agent can identify exactly what this does without opening the 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?

The phrase 'Focus an element from the snapshot' implies the prerequisite that ref must come from a prior snapshot and hints this is the tool for filling text fields, but there is no explicit when-to-use versus alternatives (e.g., press_key for keyboard-only input) or any exclusion guidance.

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 does well: it discloses the side effect of clicking (native dialog), the path constraint (absolute, inside workspace), and the return behavior (updated page snapshot). It omits failure modes and whether pre-existing file selections are replaced, but the core behavioral profile is present.

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 tight sentences: purpose first, then the click warning, then the path constraint, then return value and the untrusted-content note. Zero filler and each 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?

For a 4-parameter mutation tool with no annotations and no output schema, the description covers purpose, constraints, side effects, and return value adequately. Missing error/edge-case behavior (e.g., what happens if paths fall outside the workspace) keeps it short of a 5.

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 50% (only snapshot/screenshot carry descriptions), so the description must compensate for ref and paths. It adds real meaning for paths ('must be absolute and inside the VS Code workspace') and implies ref targets the file-input element, filling the schema gap for both required parameters.

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 precise verb+resource ('Set the files of a file input') and adds the disambiguating hint that the snapshot renders it as 'file-input, possibly hidden'. An agent can immediately tell this apart from browser_click, browser_type, and browser_select_option.

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?

Gives clear conditional context (use it when the snapshot shows a file-input, including when hidden) and an explicit negative instruction ('Do not click the input: that opens a native file dialog'). It does not name a sibling alternative, but none of the sibling tools overlap, so the guidance is effectively complete.

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 exist, yet the description still discloses real side effects: appearing text is scrolled into view and highlighted, and an updated page snapshot is returned. It also adds a security caveat about untrusted page content. The gap is what happens on timeout failure — error vs. silent return — which is left unstated.

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, zero filler, with the core wait semantics front-loaded and the security warning correctly placed last.

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 6-parameter, annotation-free, no-output-schema tool this covers behavior and return shape reasonably well. It stops short of describing timeout/failure outcomes and the mutual exclusivity of the wait modes, which an agent would need before invoking confidently.

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 67%; the four optional flags are documented there. The description maps loosely onto the two undocumented parameters by naming text appearing/disappearing and a seconds-based wait, but it never explains that text and textGone are the signal inputs or how timeSeconds interacts with timeoutSeconds. Baseline 3 fits.

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?

Opens with a specific verb+resource ('Wait until text appears or disappears on the page, or for a number of seconds'), which clearly separates it from action siblings like browser_click and read-only siblings like browser_snapshot. An agent knows exactly what condition this tool blocks on.

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 two wait modes imply when to reach for it (after a navigation or click that triggers async content), but the description never names that trigger condition or points at alternatives such as browser_snapshot or browser_navigate. Usage must be inferred from the sibling list.

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