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

Annotations only declare destructiveHint=false, so the description carries most of the burden and does it well: it discloses that on web pages the result lists what changed (new elements with refs or the new page), while in apps it returns nothing useful and a snapshot is needed. This is genuinely non-obvious behavior an agent could not infer from 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?

Three short sentences, front-loaded with the action and each carrying distinct information (web result, app behavior, batching alternative). The telegraphic phrasing ("In apps it does not") is efficient but slightly terse.

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 explains what comes back on web vs app, which is the key gap an agent would otherwise hit. Missing only minor details like failure behavior for stale refs or selector-not-found cases.

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 both parameters (session, selector) are already documented, including the ref/CSS/XPath/text selector formats. The description adds no additional meaning about parameter usage, which matches the baseline 3 when the schema does the work.

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 ("Clicks an element") and implies differentiation from snapshot and perform_actions. It doesn't explicitly say what it is NOT (e.g. vs set_value or select_option for input fields), so it stops short of full sibling disambiguation.

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 actionable routing: use perform_actions for several steps in a row, and take a snapshot in apps to observe the resulting screen. No exclusions for when clicking is the wrong choice (e.g. typing into fields), so it is clear context but not complete when/when-not 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?

Annotations only flag destructiveHint=true; the description adds the important nuance that the operation may not destroy anything at all — with detach it disconnects and leaves the session running, and that is the default for attached and Appium noReset sessions. It stops short of describing what state is lost on a hard close or what the call returns.

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 with no filler; the primary action comes first and the conditional detach semantics follow. Every clause carries distinct information about behavior.

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 two-parameter tool with only a destructiveHint annotation and no output schema, the description covers the non-obvious branch (detach defaults and override) well. Minor gaps remain around what a hard close discards, but nothing an agent needs to invoke 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 coverage is 50%: the session parameter is documented in the schema, but detach is a bare boolean with no schema description. The description fully compensates by defining both values of detach, its default per session type, and the explicit override.

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 ("Closes the session") and immediately qualifies it with the detach variant, so the agent knows exactly what the tool does. It does not name the counterpart sibling start_session, which keeps it just short of full sibling differentiation.

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 concrete conditions governing the detach behavior: attached sessions and Appium sessions with noReset are detached by default, and detach: false overrides that. This tells the agent when the default differs from expectation, though it does not state when to call this versus leaving a session open or any other alternative.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description's word "Adds" implies session state mutation that the readOnly hint does not fully surface, and it never says whether enabling is cumulative, whether groups can be disabled, or whether the newly added tools become available immediately in the same turn. With annotations carrying the safety burden, a 3 is appropriate, but the session-scoping gap is real.

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?

One sentence, front-loaded with the action, then a semicolon-delimited list where each clause earns its place by defining a distinct selectable group. The density of the parenthetical run-on hurts scanability slightly, but there is no filler or repetition.

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, so the description should say what happens after the call — whether the tools appear, whether the call is a no-op for already-enabled groups, and any session prerequisite. None of that is present. For a one-parameter enablement gate that other tools depend on, this leaves the agent guessing about call ordering.

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%, but the single `groups` parameter is an enum whose seven values the description explains in plain language ("device (emulate a phone or tablet, fake the location)"), which is exactly the meaning an agent needs to choose values. This is meaningful value beyond the bare enum list. It doesn't say how to select multiple groups or that at least one is required, leaving a small 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?

Opens with a specific verb+resource pairing ("Adds more tools") and then enumerates each addable group with a one-line purpose, so an agent can tell exactly what capability is being unlocked. It is clearly distinct from every sibling in the list, which are all action tools on the current page/session. It stops short of stating that the mechanism is a `groups` argument, but the enumeration compensates.

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 per-group notes imply when to call it (you need mocking, cookies, device emulation, etc.), which is more than nothing. However, there is no explicit statement of the wrapper use case ("if a tool you need isn't available, enable its group first"), no guidance on calling it before vs. after session start, and no note about what happens if a group is already enabled.

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?

Annotations only declare destructiveHint=false, so the description carries most of the burden and delivers real behavior: the script may `return` a value, and string args matching a selector are auto-resolved to elements. The Appium command format is also disclosed. Missing: that this executes arbitrary code with the page's privileges and typically returns the script's return value only.

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, both earning their place: the first defines the two execution modes and the return/argument behavior, the second gives the routing preference. Dense in the first sentence but front-loaded and free of 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 output schema exists, and the description compensates by saying `return` a value is how results come back. Session targeting and arg mechanics are covered between schema and description. A brief note on error behavior or the privilege of arbitrary code execution would make it fully complete for a script-execution 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?

With 100% schema coverage the baseline is 3, but the description adds semantics the schema lacks: the `script` string is JavaScript in web mode or a "mobile: <command>" in Appium, and string entries in `args` that match selectors are converted to elements. That coercion rule is not stated anywhere 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+resource: runs JavaScript in the page, or a "mobile: <command>" on Appium. It also implicitly distinguishes itself from click_element/set_value by naming the dedicated alternatives, so an agent knows this is the escape-hatch execution tool rather than a UI interaction tool.

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?

"Prefer the dedicated tools for clicks and typing" explicitly routes the agent away from this tool for common interactions and establishes it as the fallback. It also splits usage between web (JS with return) and Appium (mobile: command) modes. It stops short of saying when script execution is actually warranted (e.g., reading page state not exposed by 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the result is base64-encoded and already resized/compressed to fit model context limits, which tells the agent not to expect raw full-resolution output.

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 well-formed sentence that front-loads the action and then the return format. Every clause earns its place and nothing is padded.

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 one optional parameter documented in the schema and no output schema, the description covers the essential points: what is captured and what comes back. It omits image format (PNG/JPEG) and roughly how much compression occurs, which would help an agent reason about output size, but nothing critical to calling it 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 coverage is 100% and the single optional 'session' parameter is fully documented in the schema, so the baseline is 3. The description adds no extra meaning about session targeting or what omitting it does (the schema already says it defaults to the default session).

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 specific verb and resource ("takes a screenshot of the current page or screen") and adds the return shape (base64-encoded image, resized/compressed). It does not distinguish itself from the sibling 'snapshot' tool, so an agent cannot tell from this text alone which one to pick for visual vs. DOM capture.

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: an agent can infer this is the tool for capturing the current visual state. There is no explicit when-to-use/when-not, no routing to the closely related 'snapshot' sibling, and no mention that a session must be started 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?

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds useful context by specifying the return payload and the browser-only constraint, though it says nothing about pagination or limits on large tab sets.

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 waste, with the core purpose and return fields front-loaded ahead of the workflow guidance and scope note.

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 compensates by listing the returned fields. Combined with the pre-switch_tab workflow note and browser-only scope, an agent has everything needed to call it and use 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?

Schema coverage is 100% and there is only one optional parameter, so the schema already documents the session targeting. The description adds nothing about session semantics beyond what the schema states, making the baseline 3 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 and resource ('Lists all browser tabs') and enumerates exactly what is returned: handle, title, URL, and active flag. This is clearly distinguishable from siblings like snapshot or get_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 prescribes the workflow: 'Use before switch_tab to find the target handle or index', naming the alternative tool and the condition that selects it. The 'Browser-only' note also scopes when not to use it.

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?

Discloses side effects beyond the annotations: page state is reset, DOM, JS runtime, timers and frame context are destroyed, and the call blocks until the load event fires. That destruction note is a genuine and important disclosure that the annotations (idempotentHint=true, destructiveHint=false) do not carry; the annotations describe the abstract safety profile for external data, while the description correctly tells the agent that in-page state is lost.

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, and the operational effect (load + wait) is front-loaded before the destructive detail and the alternative. Every sentence carries 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?

Covers timing (waits for load event), state loss, and tool choice, which is what an agent needs to sequence navigation correctly. With no output schema, it does not say what the call returns (e.g., whether fresh page content is included or a snapshot call is required afterward), which is a real remaining 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?

Schema coverage is 100%, with both url and session documented in-schema, so the baseline applies. The description adds only the implicit notion that navigation happens in "the current tab" and does not explain the session parameter's targeting behavior or what happens when it is omitted.

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?

Uses a specific verb+resource ("Loads a URL in the current tab") and states the completion condition ("waits for the page load event"). This is clearly distinguishable from siblings like click_element, switch_tab, and start_session 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?

Explicitly names the alternative: "Use instead of clicking links when the target URL is known." That is a direct when-to-use / when-to-prefer-other-tool rule an agent can act on.

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?

The description adds substantial behavioral detail beyond the sparse annotations: unsupported steps are rejected before any step runs, execution stops at first failure or page-changing steps, and key presses after page-changing actions require new refs. It also explains that the tool returns what each action changed on web pages. No annotation contradiction 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?

The description is front-loaded with the core purpose and every sentence carries useful information about execution, stopping, or parameter meaning. The stopping-conditions sentence is dense but necessary for a batch tool; overall it is appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex nested-action tool with no output schema, the description covers purpose, pre-validation, stopping semantics, and value meaning well. It does not describe the return shape or whether changes from earlier steps persist after a stop, which are minor remaining gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 50% schema description coverage, the description compensates by explaining that 'value' means text for fill, an option for select, and keys for press. It also clarifies selector refs through the stopping guidance, though it does not explain every nested field such as 'times' or the session parameter beyond what the schema already 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 states a specific verb and resource: it runs several UI actions in one call, with an example of filling and submitting a form. It implicitly distinguishes itself from single-action siblings like click_element or set_value by emphasizing batching, though it does not name those alternatives 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?

Usage is implied by 'Runs several actions in one call' and the form-filling example, so an agent can infer this is for multi-step sequences. However, there is no explicit guidance on when to choose this tool over individual sibling tools such as click_element or press_key, nor any 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?

Annotations already declare destructiveHint=false, and the description usefully adds that the result reports what changed on the page, which goes beyond the annotation. However, it says nothing about permission or focus requirements (what happens when no element is focused), which is the main behavioral risk for this action.

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 doing distinct work: action, return behavior, and sibling routing. Nothing repeats the name or title and nothing is 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?

With no output schema, the description correctly fills the gap by stating the result lists page changes, and params are fully covered by the schema. The remaining gap is how focus is established before pressing (click_element/switch_frame), which an agent must infer.

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 baseline is 3, but the description adds key-syntax meaning ('Control+a') that the schema's bare 'Key or combination' does not convey. The times and session parameters are left entirely to the schema, which is acceptable given full coverage.

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 (presses a key or combination) plus the target scope (the focused element), and gives concrete examples like Enter, Tab, Control+a. It explicitly separates itself from perform_actions for multi-step sequences, so an agent can pick between them without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The line 'Several steps in a row: perform_actions' names the sibling and the condition that selects it, which is exactly the routing guidance an agent needs for short vs. chained input. It does not mention alternatives for text entry (e.g., set_value) or what to do if nothing is focused, so exclusions are only partially covered.

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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description goes well beyond annotations by explaining query sensitivity ('a sentence dilutes the ranking'), failure recovery ('retry with the exact page title'), the fullPage switch, and the browsing pseudo-URLs. It also specifies that results are excerpts with source URLs, giving the agent a clear behavioral model.

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 front-loaded with purpose and return format, then moves to usage triggers and query examples. Every sentence adds operational value: query style, collision warning, retry strategy, fullPage, browsing alternative, and citation requirement. There is no filler or repetition.

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 search tool with no output schema, the description covers input format, expected output, edge cases, and an alternative browsing path. It tells the agent what to return (excerpts with path/section/URL) and how to cite pages. Nothing essential for correct invocation 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 coverage is 67%, with query and fullPage already described in the schema. The description adds valuable semantics for query formation (2-3 distinctive keywords, examples, page titles beat paraphrase) and reinforces fullPage behavior. The limit parameter is not covered in prose, but its schema constraints (default 5, min 1, max 20) are self-explanatory, so the gap is minor.

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 (Search), resource (official WebdriverIO documentation), and return value (most relevant excerpts with page, section and source URL). It clearly distinguishes itself from the sibling tools, which are all device/session automation actions, by stating it is for documentation lookup before answering questions.

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 'Use before answering any question about WebdriverIO APIs, configuration, services, reporters, selectors, or debugging.' It also provides concrete query strategies, retry advice on word collisions, and an alternative browsing mode via wdio://docs/index and wdio://docs/page/{slug}. This is strong when-to-use and how-to-use guidance with no ambiguity.

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?

Annotations only declare destructiveHint=false and a title; the description adds genuine behavioral context beyond that — that it is browser-only, limited to vertical direction, and by implication a viewport-state change rather than a data mutation. It does not describe what happens on scroll to boundary or return values, which keeps it from a 5, but it clearly fills gaps the annotations leave.

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 action front-loaded followed by the scope constraints. Every clause carries distinct information — verb, unit, platform restriction, direction restriction — with nothing repeated.

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 3-param tool with a fully-described schema and no output schema, the description supplies the essential constraints an agent needs. The main residual gap is the reference to a non-sibling 'swipe' tool and the absence of edge-case behavior (e.g., scrolling past the page end), but overall it is sufficient to call 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 description coverage is 100%, with direction enum and pixel default already documented inline, so the schema carries the parameter burden. The description reinforces the vertical-only direction constraint and the pixel unit, adding marginal but non-redundant meaning. Baseline 3 is appropriate when the schema is fully documented.

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 (scrolls), the resource (the page), and the unit of movement (vertical pixel amount). It explicitly delimits scope — vertical only, browser-only — so it is easily distinguished from interaction siblings like click_element or press_key. No ambiguity about what the tool 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?

Names an explicit alternative with its condition: 'for mobile scrolling use swipe.' It also states the when-not condition for horizontal movement ('no horizontal scrolling'). It falls short of 5 because the referenced alternative (swipe) is not present among the listed sibling tools, so the routing advice points outside the available set.

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?

The description adds useful behavioral context beyond the annotations: the result lists what changed on the page, which is valuable because there is no output schema. It also implicitly conveys a non-destructive interaction, consistent with destructiveHint=false, though it does not mention event side effects or authorization needs.

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 front-loaded with a distinct point: purpose, result behavior, and multi-step alternative. There is 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 simple selection tool with full schema coverage and no output schema, the description covers the essential behavior and return context. It could be slightly richer about page-change side effects or when not to use it, but nothing critical 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 selector, value, and session. The description adds only the phrase 'by its text' for the value parameter, which is already covered by the schema's 'Option text' description.

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 specific verb and resource: selecting an option of a <select> by its text. This clearly distinguishes it from siblings like click_element or set_value, which do not target a select option by text.

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 usage guidance for chaining several steps by pointing to perform_actions. However, it does not explicitly state when to use this instead of set_value or click_element for similar interactions.

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?

Annotations only state idempotentHint=true and destructiveHint=false; the description adds real value by explaining that on web pages the result lists what changed (new elements with refs or the new page), while in apps it does not and a snapshot is required. That return-behavior divergence is exactly the kind of context an agent cannot infer from structured fields, though waiting/retry behavior is still 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 sentences, no padding, and the core action is stated first with routing guidance following. The second sentence ('In apps it does not') is slightly elliptical, requiring the reader to carry over 'lists what changed', but that is a minor cost.

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, and the description compensates by describing what the response contains in each environment. Combined with the schema and annotations, an agent has everything needed to call this correctly and interpret 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?

Schema coverage is 100%, so selector, value, and session are already fully documented in the schema. The description only indirectly reinforces the selector concept via 'new elements with refs' and adds no syntax or format detail beyond the schema, making the baseline 3 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 gives a specific verb and resource: 'Replaces the text of an input or textarea.' It is immediately distinguishable from sibling tools like click_element or perform_actions, and the scope (text-entry elements) 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?

It names the alternative explicitly ('use one perform_actions call') along with the condition that selects it ('To fill several fields or fill and then click'). It also directs the agent to snapshot when running in an app, so both routing decisions are 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds real behavioral detail beyond that: the default drops plain text and keeps only interactive elements, full:true restores it, and viewport cannot be combined with find. It doesn't say anything about output size or truncation on large pages.

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 paragraph that opens with what the tool is and an example, then moves to how to use the refs. Dense but every clause carries information; only mild run-on density keeps it from a 5.

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 5-parameter read tool with full schema coverage, no annotations gap, and no output schema, the description supplies the output shape and mode interactions an agent needs. Session and scope behavior are left entirely to the schema, a minor remaining 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?

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine semantics beyond the schema: 'find returns only the parts of the page that contain the text (with their refs)' and the exclusion between find and viewport are behavioral constraints the schema does not encode. scope and session are left to 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 states precisely what the tool returns — the page as an accessibility tree with refs — and includes a concrete output example (`button "Save" [ref=e3]`). It does not explicitly distinguish itself from get_screenshot or query_docs among the siblings, so it falls short of a 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?

It routes the agent downstream clearly: refs go to perform_actions for multi-step work, or to click_element/set_value/select_option for a single action. It also states the find+viewport incompatibility, but gives no guidance on when to prefer this over get_screenshot or query_docs.

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?

Annotations provide only destructiveHint: false, so the description carries most of the burden — and it does disclose the most dangerous behavior: the active session is closed unless onExisting: "keep". It also surfaces the headless 1280x800 default and the CDP attach mode. It does not cover cloud provider credential requirements (env-based per the schema) or what the tool returns, which keeps it from 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 sentences, all front-loaded: core action, destructive side effect, then orientation for the two most confusing options. Nothing repeats the schema verbatim and no sentence 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?

For a 42-parameter, nested-object tool with almost no annotation coverage and no output schema, the description covers only the top gotchas. It omits the platform→required-parameter matrix, cloud credential prerequisites, and any hint of what a started session returns or how to address it afterward — gaps an agent will hit on a first call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 42 parameters at 76% schema description coverage, the schema already does most of the parameter work and baseline 3 applies. The description adds real meaning to the highest-risk flags (onExisting, attach, navigationUrl, headless/window defaults) but leaves the platform-conditional requirements — browser for platform browser, deviceName for mobile — entirely to 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?

Specific verb + resource ('Starts a browser, Electron app or mobile app session'), and its role as the counterpart to close_session is unambiguous. The three supported platforms are named. It stops short of naming sibling alternatives (navigate, close_session), so it lands at 4 rather than 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?

Usage is implied rather than stated — an agent infers this is the entry point before navigate/click_element/etc., and gets concrete guidance for navigationUrl and attach. There is no explicit 'call this first' instruction and no discussion of when a session is already live versus not, so guidance is contextual rather than directive.

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?

Annotations only declare idempotency and non-destructiveness; the description adds the important stateful behavior that subsequent tools operate inside the frame until switched back, and that the frame's elements are returned. That is real context beyond the structured fields, though auth/pagination/error behavior is unmentioned.

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 core action and followed by the two facts an agent needs (scoping persistence and return value). 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 only two params and no output schema, the description covers the action, the return value ('the frame's elements'), and the stateful implication of the switch. Nothing critical is missing for correct 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?

Schema coverage is 100%, so both parameters are already documented. The description restates the 'ref or selector' and omit-for-top-page semantics, adding little beyond the schema, so 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 (switches) and resource (iframe), plus the dual mode: enter a frame or return to the top page. The iframe framing distinguishes it from switch_tab implicitly, though it never names that sibling 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?

Gives a clear conditional ('omit selector to return to the top page') and the persistence rule ('later tools act inside the frame until you switch back'), which is genuinely usable guidance. It does not, however, explicitly contrast with switch_tab or say when frame switching is unnecessary.

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?

Annotations already declare idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuine value by disclosing the persistent side effect that subsequent tools operate on the switched tab, but says nothing about behavior when neither index nor handle is supplied or what happens to the previously active tab.

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, front-loaded with the action and target, with no filler. The downstream-effect note is placed immediately after the action statement where it is most useful.

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 small, annotation-covered tool this is close to sufficient, but all three parameters are optional and the description never explains what happens with no arguments given — a real ambiguity for an agent deciding whether it must supply index or handle.

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, and the description adds the either/or framing (by handle OR by index) plus a pointer to get_tabs as the source of handles, which the schema does not state. It says nothing about the optional session parameter, but that is 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 (switches) and resource (tab) with the two addressing modes, and cross-references get_tabs. It does not explicitly contrast with the sibling switch_frame, so an agent must infer tab-vs-frame distinction from the names alone.

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?

"Later tools act on that tab" tells the agent this is a setup step that must precede other browser actions, and "see get_tabs" points at how to obtain valid targets. It stops short of stating when not to use it (e.g., when already on the target tab) or how it differs from switch_frame.

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