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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the data source is a local JSONL file written by every run, and it discloses what the flaky view surfaces (pass/fail flips, broken or regressed tests). It omits defaults/limits and any note on history retention or staleness.

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 dense sentence with a parenthetical, front-loading the action and data source before enumerating view behaviors. Every clause carries information; the view enumeration is the longest but earns its place. Slightly heavy in a single sentence, but 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 must carry more weight, and it does explain the return semantics of each view. However, projectRoot (presumably how the history file is located) and limit/lastRuns bounds are left entirely to the schema, leaving the picture partially incomplete for a 5-parameter 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 60%, so baseline is 3. The description meaningfully expands the 'view' enum by explaining the semantics of each value, adding value over the schema's bare listing. But it says nothing about limit, projectRoot, or lastRuns, so the gap in coverage is not compensated.

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 (Analyze) and resource (local run history), and names the exact backing file .playwright-e2e-mcp/history.jsonl. It enumerates the three view modes with their behaviors, so the agent knows what output families are available. It does not explicitly differentiate from siblings like diagnose-flaky or get-failure, which keeps it from 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?

The description tells the agent what each 'flaky', 'patterns' and 'test' view does, which implies which view to pick for a given need. However, it never states when to use this tool instead of diagnose-flaky, get-failure, or get-run-status, nor any prerequisites. Usage is implied rather than explicit.

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 declare destructiveHint=true and openWorldHint=true; the description supports this by disclosing the baseline-save behavior and that a red-highlighted diff image file is written as a side effect, which is real context beyond the flags. It does not warn that re-saving a baseline overwrites the prior one, nor mention auth/session needs (storageState), leaving one meaningful destructive consequence implicit.

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?

Front-loaded with the tool's identity, then the baseline/compare lifecycle, then the artifact written — three useful sentences with no filler. The long parentheticals ('WHERE they changed (bounding regions), and the average color shift ("blue → red")') are arguably denser than needed but still informative.

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 15-parameter tool with nested objects and no output schema, the description usefully summarizes the return content (change count, bounding regions, color shift), substituting for the missing output schema. It still omits where the diff image is written and whether results come back as structured data, so it is strong but not fully complete.

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

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

Schema coverage is 80%, so the schema largely documents url, name, action, selector, tolerance, and pixelThreshold itself. The description only loosely maps to parameters ('page (or element)' for url/selector, baseline lifecycle for action) and adds no format, default, or unit detail beyond the schema, so the 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?

Opens with a specific verb+resource label ('Visual regression check') and then concretely describes the pipeline: screenshot a live page or element, compare to a stored baseline, report pixel deltas, bounding regions, and color shift. An agent can distinguish this from inspect-page, validate-selector, or run-test 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?

Clearly states the operating model: 'First call saves the baseline; later calls compare,' which tells the agent how to sequence calls. It does not name sibling alternatives or when NOT to use it (e.g., prefer inspect-page for DOM debugging), so it stops short of full routing 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?

Adds behavior the annotations don't convey: retries are disabled during diagnosis, tests are executed multiple times, and the result varies in the described way (pass/fail counts, error-signature variance). Annotations cover safety (destructive/idempotent/openWorld), so the description is free to focus on run semantics, which it does well.

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 dense sentence, front-loaded with the action and the three possible verdicts. Every clause carries information; 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?

For an 8-parameter tool with no output schema, the description covers the output shape (verdict categories and what each contains) and the default targeting, which is the critical missing piece. Remaining parameters are handled by the schema, so the gap is minor.

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

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

Schema coverage is 88% and already documents runs, testFiles, timeoutMs, and config. The description repeats the testFiles and runs defaults without adding format or interaction details, so it does not materially extend the schema. 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 (run failing test repeatedly), the key constraint (retries disabled), and the output (evidence-based verdict with three named outcomes). An agent can distinguish it from run-test purely from this description.

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?

Clear context: use when a test is failing and you need to know whether it's a real bug, flaky, or a one-off, and it defaults to the most recent failure set. It doesn't explicitly name a sibling to use instead for plain execution, but the diagnostic framing makes the boundary with run-test obvious.

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=true, openWorldHint=true, and non-idempotent, so the safety profile is covered. The description earns credit for disclosing behavior beyond that: it scans the git working tree/last commit (mtime fallback), extracts specific locator types with source locations, optionally cross-checks the live page, writes the spec, and returns next steps. It only stops short of flagging the overwrite hazard explicitly.

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 that leads with the verb and resource, then enumerates the pipeline steps compactly. Dense but every clause carries information with no filler, so it is easy to scan.

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 destructive, open-world generation tool with nine params and no output schema, the description covers the process and notes the return ('returns next steps'). It omits where the spec lands by default and any warning about writing to disk, but is otherwise complete enough 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 description coverage is 100%, so the schema documents all nine parameters and the baseline is 3. The description adds contextual meaning for a few (live cross-check implies liveInspect, project scanning implies projectRoot), but does not explain file, write, overwrite, or config beyond what the schema already states.

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 (Scaffold) and resource (Playwright test spec) and adds the key qualifier 'using the project's REAL selectors', so the intent is unambiguous. It does not name or contrast with any sibling (e.g. validate-selector, inspect-page, run-test), so it stops short of explicit 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?

The description explains the mechanism but never says when to reach for this tool versus siblings like validate-selector, inspect-page, or run-test. No when-to-use, when-not-to-use, or ordering guidance is provided, 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?

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so safety is covered; the description adds real value by disclosing that it operates on the stored output of the last run-test execution and by enumerating the failure-kind taxonomy (assertion/timeout/browser-crash/syntax/config/server-unreachable). It omits the failure modes of the tool itself, e.g. what happens when no failures exist or the index is out of range.

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, front-loaded with what is returned, with no filler. It is heavy on enumeration and could be split, but every clause carries information the agent needs.

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 must describe the return value, and it does so thoroughly (message, code frame, expected vs actual, stack trace, network requests, console errors, failure kind, next steps). The remaining gap is edge-case behavior — no failures recorded, invalid index, or stale report — which would matter for reliable 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 documented in the schema, including the 1-based index and the default of 1. The description only implies the index scoping ('one failure from the most recent run-test execution') and never mentions projectRoot's re-read role, so it adds little beyond the schema — the baseline 3.

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 (analyze) and resource (one failure from the most recent run-test execution) plus the exact payload the agent will get back. It is clearly distinguishable from siblings like analyze-history (historical) and suggest-fix (remediation), which serve different intents.

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 says 'Use run-test first,' establishing the prerequisite ordering against the sibling that produces the report. It does not, however, say when to prefer suggest-fix or diagnose-flaky after a failure is retrieved, so the routing guidance stops one step short of 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?

Annotations declare idempotentHint=true, destructiveHint=false and, notably, readOnlyHint=false; the description explains why by disclosing that cancel terminates the run and that waitSeconds blocks. It also states the default-run fallback, which annotations cannot express. It does not restate the schema's 55s wait cap or describe failure/error states, keeping it out of 5 territory.

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 dense sentence front-loads the return shape (progress vs final result), then the parameter semantics, then the default. No filler, though the semicolon-chain style is telegraphic and the waitSeconds 55s bound lives only in the schema.

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 naming the return payload (tests done/total, failures so far, final result) and the downstream relationship with get-failure. Missing only error/timeout behavior and what a cancelled run returns.

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 33% (just waitSeconds), so the description must carry runId and cancel. It does: 'cancel stops it' defines cancel, and 'Default: the latest run' tells the agent runId is an optional selector. It stops short of 5 only because runId's accepted format/scope (e.g., run id vs test id) is left implicit.

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 (retrieve progress or final result of a run-test background run) and names the two siblings it relates to: run-test produces the run, get-failure consumes the result. An agent can place it precisely in the workflow 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?

Implies the polling workflow (progress vs final result), explains that waitSeconds blocks and cancel aborts, and states the default (latest run) for the no-arg case. It never explicitly says when NOT to use it versus get-failure or list-tests, so it stops short of 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?

Annotations already supply readOnlyHint, openWorldHint and idempotentHint, so the safety profile is covered. The description adds meaningful behavior beyond that: the browser runs headless, actions are executed before inspection, and console messages are captured. It doesn't say how failures (nav timeout, missing locator) surface, which is the remaining 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?

It is three tight, front-loaded sentences with no filler; the core behavior leads and the usage hints follow. Phrasing is telegraphic ('storageState/headers open it signed in'), which is efficient but slightly compressed for a 13-parameter tool.

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 13 parameters, nested action objects and no output schema, the description does the important work of enumerating what is returned and how auth/actions affect the result. Missing are error/timeout behavior and truncation semantics, but the essentials for correct invocation are present.

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 92%, so the baseline is 3, but the description adds real meaning: storageState/headers are framed as the signed-in path and actions as the way to reach a state (modal, step 3). The view enum is likewise described by cost/size rather than just restating the enum values.

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 concrete verb+resource (open a URL headlessly and return its elements) plus the returned payload: locators, CSS selectors, visibility, text, console messages. It is far more specific than a sibling like run-test, but it never explicitly contrasts itself with validate-selector or generate-e2e-test, so the agent must infer the boundary.

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 operational context: storageState/headers open the page signed in, actions click/fill first to reach a state, and view 'locators' is the compact/cheapest map. It does not name an alternative tool or state when-not to use this one, 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?

Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), but the description adds genuinely useful behavior: a primary `playwright test --list` path with a source-scan fallback when the install or config is broken, plus the promise that it reports why. It does not mention cost, latency, or whether the fallback results are less complete, 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?

Two tight sentences: the first front-loads what is listed and what is returned, the second supplies the fallback behavior. No filler, no restatement of the title.

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 partially compensates by naming the returned fields and explaining the dual-path execution. Combined with a fully documented 5-parameter schema and zero required parameters, an agent has nearly everything needed; only the shape of the fallback 'reason' report is left unstated.

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 (limit, config, filter, testDir, projectRoot) is already documented with defaults and constraints in the schema. The description adds only the generic phrase 'with optional filtering', which maps loosely to the filter param without adding syntax or format detail. 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 (List) and resource (Playwright tests available in the project) and even enumerates the returned fields (file, line, full title, projects). No sibling tool in the set performs listing, so an agent can distinguish it from run-test, get-run-status, or generate-e2e-test 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 mention of 'optional filtering' implies a discovery use case (finding tests before acting on them), but the description never states when to reach for this tool versus run-test or get-run-status, nor does it set any preconditions. Usage is inferable 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?

Goes well beyond the annotations by describing the failure taxonomy it diagnoses (missing installs, dead dev servers, syntax errors, crashes, timeouts), the timeout behavior (kills the process tree, keeps partial results), progress reporting, and the background run-id workflow. With destructiveHint=true already declared, it usefully clarifies that a timeout kill is scoped and partial results survive, though it doesn't state side effects like artifact writes or install attempts.

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 dense sentences, front-loaded with what the tool does and its output before behavioral details. Nearly every clause earns its place, though the telegraphic style ('stats plus each failure's file:line, kind and message') is compact to the point of being 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?

For a 14-parameter runner with no output schema, the description does the necessary work: it describes the return payload, progress reporting, timeout kill behavior, and how to retrieve results from long suites via background plus get-run-status. Remaining gaps (artifact locations, interaction with sharding) are minor given the rich schema.

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

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

Schema description coverage is 86% and the schema itself is highly detailed (allowlisted flags, timeout semantics, last-failed loop), so the parameters are already well documented. The description adds the partial-results behavior on timeout and the background polling workflow, but most parameter meaning is carried by the schema rather than the prose.

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 ('Run the project's Playwright tests') and names the exact output shape: stats plus each failure's file:line, kind and message. It also carves out a distinct role from siblings by framing itself as the runner that records runs for analyze-history and drops a run id for get-run-status.

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 operational context: background:true returns a run id for long suites and you poll get-run-status, which names a concrete alternative and the condition selecting it. It also points forward to analyze-history. It stops short of explicit when-not-to-use guidance (e.g., when to prefer list-tests or get-failure instead).

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 flag destructiveness and non-idempotency, and the description adds behavior annotations cannot express: the verify-then-revert cycle ('re-runs the test and reverts if still red'), the returned artifacts (diff and confidence), and the refusal condition for genuine app bugs. This is exactly the extra context an agent needs before invoking a destructive 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 dense sentences, front-loaded with the core action and repair mechanism before the apply/verify semantics and the refusal caveat. Every clause carries information, though the middle sentence packs several behaviors into one run-on structure.

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 10-param destructive tool with no output schema, the description covers the mutations, the reversion guarantee, what is returned (diff, confidence), and the refusal case. It leaves auth/session params (headers, storageState) and config/timeout handling to the schema, which is acceptable given their 90% coverage.

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 90%, so the baseline is 3, but the description meaningfully extends key params: it explains that apply:true triggers a write plus verification with rollback, and that url heals against the live page instead of the trace snapshot — detail beyond the schema's terse 'default: diff only' and 'Heal against this live page'.

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 with scope: 'Patch a failure from the last run', and details the two concrete repair modes (drifted locator remap, changed expected text). This clearly separates it from siblings like get-failure (read) and run-test (execute).

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 for use ('failure from the last run') and an explicit exclusion boundary ('Refuses when the element is truly missing (app bug)'), plus a variant path (live url vs trace). It does not name alternative siblings such as validate-selector or inspect-page for pre-healing analysis, so it stops short of full alternative 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?

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so the description earns credit for adding real context: it needs a live, possibly authenticated page (storageState/headers) and can be driven through intermediate states via actions. It stops short of noting the mild tension that 'actions' can click/fill the live page while the tool is annotated read-only, or any rate/timeout behavior beyond what the schema states.

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?

Front-loaded with the verb and fully packed into two sentences with no filler; every clause (locator kinds, live page, output list, accepted inputs) earns its place. The parenthetical locator examples make it dense but readable rather than 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?

For an 8-parameter tool with nested action objects and no output schema, the description usefully enumerates what the call returns, which compensates for the absent output schema. The remaining gaps (defaults, pagination-style limits, behavior when zero or many matches occur) are minor and partly covered by the schema.

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

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

Schema description coverage is already 88%, so the baseline is 3, and the description goes slightly beyond by calling out storageState, headers and actions as accepted inputs and explaining the selector semantics with concrete locator syntax. It does not clarify defaults for timeoutMs or projectRoot, but the schema covers those.

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 (validate/check) and resource (CSS selector, Playwright selector or locator) plus the exact scope: against a live page. It enumerates the outputs the agent gets back (validity, match count, sample matches, sturdier verified locator), which cleanly distinguishes it from siblings like inspect-page or run-test that operate on whole pages or suites.

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 'actions need exactly 1' gives an implied usage rule (validate before acting), and 'on a live page' signals the required context, but there is no explicit when-to-use/when-not statement and no sibling is named as the alternative. The agent must infer that this is the pre-flight check rather than, say, run-test or suggest-fix.

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