playwright-e2e-mcp

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 comes from a local file that every run and load-report writes, implying history is unavailable before any run exists. It omits behavior on empty/truncated history and how cloud merging affects results.

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 artifact and its provenance are front-loaded, followed by a compact semicolon-delimited mode list; every clause carries information. The single dense sentence is slightly harder to scan than a short bullet-style enumeration would be, but nothing is wasted.

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 read-only, zero-required-parameter tool with no output schema, the description covers the data source and all six modes, which is what an agent needs to choose a view. It stops short of describing result shape or the empty-history case, but the annotations and schema carry the rest.

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%, so the schema already documents view, source, lastRuns, and the test filter. The description adds real meaning for 'patterns' and 'test' views that the schema's enum description lacks, but says nothing about limit, projectRoot, or the default 30-run window, leaving the coverage gap partly unfilled.

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, names the exact backing artifact (.playwright-e2e-mcp/history.jsonl) and its provenance (written by every run and load-report), then enumerates the six analysis modes. An agent can distinguish this from diagnose-flaky or get-failure 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?

Each view is mapped to the question it answers ('flaky' ranks flipping tests, 'patterns' groups by cause, 'test' shows one timeline), which effectively tells the agent which mode to select. It does not state when to prefer a sibling tool such as diagnose-flaky, nor any preconditions like 'requires prior runs'.

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 and openWorldHint, so the safety profile is covered. The description adds useful behavior beyond them — result ordering (worst first), what each violation carries, and the auth/multi-step entry paths — but says nothing about runtime cost, rate/timeout limits, or failure modes of a live-page audit. Solid additive value, not rich.

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 front-loaded: capability and return value first, conditional entry paths second. No filler, and every clause carries information an 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?

For an 18-parameter tool with nested objects and an output schema, the description covers the essential mental model: what is audited, how results are ordered, and how to reach authenticated or multi-step pages. Minor gaps (timeout budget, projectRoot/browser selection, selector scoping) are fully documented in the schema, so nothing blocking 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 89%, so the schema already documents nearly every parameter including defaults and enums. The description only gestures at the storageState/headers/actions trio by purpose (login, post-load state) rather than adding syntax or interaction details like the one-fresh-browser-per-call constraint. 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 and engine ("Run axe-core on a live page") plus the default rule set (WCAG 2.2 AA) and the return shape (violations worst first with verified Playwright locators, fix, regression check). The accessibility-audit domain is unmistakably distinct from siblings like audit-performance and audit-tests, so an agent can select it without opening a 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 second sentence gives concrete usage contexts: pages behind a login (storageState/headers) or states reachable only after steps (actions). What is missing is explicit routing away from alternatives — nothing says "use audit-performance for timing" or when not to run this, so it stops short of the top band.

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/openWorldHint/idempotentHint, and the description adds meaningful context beyond them: this is a lab (headless Chromium) measurement, INP is only reported 'when actions interact', and results include rated verdicts against Google thresholds or custom budgets. It stops short of disclosing cost/runtime (each call launches a browser, so multi-run audits are slow) or that it requires a Playwright project context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Effectively one long sentence that front-loads the verb, the measured metrics, and the outputs before trailing capabilities, which is well adapted to a 20-parameter tool. It is dense and slightly run-on, and 'in headless Chromium' partially duplicates the browser parameter, but nothing is wasted.

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?

An output schema exists, yet the description still usefully previews what comes back (ratings, locators, request lists, budget verdict) and covers measurement conditions and the optional auth/mock/interaction inputs. It omits practical prerequisites (a Playwright project root, long runtimes for multi-run medians) that an agent would want before invoking it repeatedly.

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 90%, so the schema already carries the parameter documentation burden. The description calls out useful capability clusters (storageState/headers for auth, actions for reaching state, routes for mocking, throttled phone, median of runs), but it adds no syntax or constraint detail beyond what the schema already says. 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 and resource ('Measure a page's lab Web Vitals') and enumerates the exact metrics plus the derived artifacts (LCP element locators, shifting elements, heavy/render-blocking requests, budget check). This is clearly distinguishable from siblings like audit-accessibility, inspect-page, and run-test.

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 mention of budgets and 'the spec' hints at CI/pre-ship gating and the throttled/median options hint at mobile profiles, but the description never says when to choose this over audit-accessibility or run-test, nor does it state prerequisites or exclusions. An agent must infer the fitting scenario.

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 destructiveHint=true and openWorldHint=true; the description earns credit by explaining exactly what destruction looks like (rewrites mechanical findings, re-runs touched files, restores on failure) — a rollback guarantee the annotations cannot convey. It stops short of noting that without fix:true the call is a non-mutating scan, and says nothing about auth or project prerequisites.

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 audit purpose and its risk taxonomy, then the fix behavior. The parenthetical list is long but each item is load-bearing; no filler sentences or restated 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?

An output schema exists, so return values need no explanation, and the mutation path is fully described including the restore-on-failure safety net. What's missing is setup context — that a Playwright project/config and local history must exist for the ranking and verify steps to work.

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 all ten parameters are self-documenting; baseline is 3. The description reinforces fix and hints that history weighting exists, but adds no syntax or interaction detail 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+resource (audit Playwright test code for flake risks), enumerates the exact anti-patterns it looks for, and adds a second dimension (ranking files by historical flakiness). This is clearly distinguishable from siblings like diagnose-flaky (single failure) and analyze-history (run data only).

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 what fix:true does but never states when to reach for this tool versus diagnose-flaky, analyze-history, or suggest-fix, nor any when-not conditions. Usage is implied (scan-and-optionally-repair) rather than prescribed.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true, but the description adds important behavior not in annotations: it runs in a temporary worktree so 'your checkout is untouched', and it reports the first bad commit with diff summary and failure. It could still mention cost/duration or that it requires a git repo with runnable tests, hence 4 rather than 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 sentences, front-loaded with the core action and results, and the second sentence packs the semantics of defaults and worktree isolation without waste. 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?

An output schema exists, so return-value detail is not required, and the description already says what is reported (first bad commit, diff summary, failure). Combined with rich parameter descriptions and annotations, an agent has enough to call this correctly and understand its side effects.

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 baseline is 3. The description still adds meaning beyond schema: it explains where the 'good' default comes from (newest commit where run history saw the test pass) and implies the scope of the search. The schema already covers the remaining parameters, so this is appropriately above baseline but not 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 goal ('find the commit that broke a test') and explains the mechanism: binary-search git history between good and bad commits, running the test in a temporary worktree. This is clearly distinguishable from siblings like get-failure (report lookup) or analyze-history (history analysis).

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 usage context: 'repeat' should be raised for flaky failures, 'good' defaults to the newest passing commit from run history, and the schema description prefers grep over :line. It does not explicitly name alternatives (e.g., analyze-history or diagnose-flaky) or say when not to use it, so it falls just 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 declare readOnlyHint and idempotentHint, so the safety profile is covered; the description adds genuine value by disclosing the outcome model — hard BLOCK on deleted assertions, skipped/removed tests and .only, versus WARN on weaker matchers, waitForTimeout, force: true, swallowed errors and raised timeouts/retries. It does not say what the response contains, but an output schema exists to cover that.

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 packed sentences, front-loaded with the guard's purpose before modes and severity rules. The BLOCK/WARN enumeration is dense but every item carries decision-relevant information, and nothing is redundant.

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 full schema coverage and the presence of an output schema, the description supplies everything an agent needs to decide to call it: purpose, trigger, mode selection and severity semantics. Minor gap: it never clarifies scope boundaries (which files are scanned by default beyond spec files and playwright config) or whether projectRoot affects that scope.

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 explains base, file, after, files and projectRoot. The description only adds the framing that 'file + after' is a paired mode and that base defaults to uncommitted changes, both of which are already in the schema text — baseline 3 is correct.

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 ('check that changed tests were not made to pass by checking less') and immediately frames it as a guard against a concrete failure mode, which distinguishes it from siblings like suggest-fix or audit-tests. The two comparison modes (git ref vs. proposed file) further sharpen what the tool actually 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?

Gives an explicit trigger: 'Run it after any AI fix, before committing,' plus mode selection guidance ('base' defaulting to HEAD for uncommitted changes, or file + after for a proposed fix). It does not name a sibling alternative or state when not to use it, so it falls 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 declare destructiveHint=true, openWorldHint=true and idempotentHint=true; the description adds useful output context (diff image with red highlights, bounding regions, color shift). However, it never warns that saving a baseline overwrites the stored one (a destructive act), nor mentions network/auth requirements implied by openWorldHint. It also says 'first call saves the baseline', which conflicts subtly with the schema default action='compare'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the core purpose and the report contents; every sentence carries information. Minor waste in the parenthetical color example, and the baseline sentence muddies rather than clarifies the action 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?

With no output schema, the description usefully enumerates the return contents (pixel count, regions, color shift, diff image), which is the biggest gap it needed to fill. It falls short on the baseline lifecycle and destructive overwrite semantics, which matter for a 21-parameter mutation 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 81% and 21 parameters are documented in the schema, so the baseline score is 3. The description adds no parameter-level meaning (e.g. tolerance vs pixelThreshold interplay, when to supply storageState or actions) beyond hinting at page-vs-element capture via 'live page (or element)'.

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 combination ('Visual regression check: screenshot a live page (or element), compare it to a stored baseline') and describes what is reported: pixel count, bounding regions, and average color shift. This clearly separates it from siblings like inspect-page or run-test, and 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?

'First call saves the baseline; later calls compare' gives some lifecycle context, but it does not name when to prefer this tool over siblings such as inspect-page or run-test, nor when not to use it. It also sits awkwardly against the schema's `action` parameter whose default is 'compare', leaving the agent unsure whether baseline creation is automatic or must be requested explicitly.

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 disclosing the execution model: repetitions run in one process by default, timeoutMs is per run and multiplied by runs for a single --repeat-each process, and separateProcesses exists for cold-start/global-setup flakes. It never addresses the destructiveHint=true implication (tests may mutate state) or permission requirements, which is the main 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?

Front-loads the core action and verdict taxonomy in the first sentence, then adds the two opt-in modes in a compact clause structure. It is dense and slightly long, but nearly every clause carries actionable information; only the repeated restatement of the default failed-test set is redundant.

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 11-parameter diagnostic tool with an output schema and annotations already present, this covers the default behavior, the two special modes, process model, and timeout semantics. An agent can call it correctly with zero configuration and understands what each verdict means.

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 91%, yet the description still adds semantic value: isolate distinguishes shared-state parallelism bugs from in-test flakiness, order uses Playwright 1.64+ shuffle and returns a reproducing seed plus culprit, and defaults are restated for testFiles and runs. The 10x timeout multiplication for one process is a genuinely non-obvious clarification.

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 (repeat failing tests with retries disabled) and the exact output produced (per-test verdict: CONSISTENTLY FAILING / FLAKY / NOT REPRODUCING). This clearly separates it from siblings like run-test and bisect-failure, which do not produce evidence-based flakiness verdicts.

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?

Explains the default target set (tests that failed in the most recent run) and when to reach for the isolate and order modes, including the diagnostic question each answers. It does not explicitly say when to prefer this over bisect-failure or run-test, so the alternatives routing is implied 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?

Beyond the annotations (destructive, openWorld, non-idempotent), the description discloses real side effects: it writes a spec to disk, optionally runs that spec once to prove it passes, hits the live page, and overwrites only specs it generated. It does not cover prerequisites (Playwright/browser availability), what happens on failure of the verification run, or timeout behavior, so it stops short of full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action before the mechanism, so the agent gets the headline immediately. The second sentence is dense with nested parentheticals and could be split, but 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?

With 15 parameters, no output schema, and two operating modes that write files and execute a browser, this is a complex tool and the description covers both modes plus the returned 'next steps'. The main gaps are failure semantics of the verification run and any environment prerequisites, which matter for a destructive, open-world 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 93%, so the baseline is 3 and the schema carries parameter meaning. The description still adds value the schema cannot: it explains the semantic coupling between `steps`, `verify`, `assertScope`, `storageState`, and the end-state assertions the generated spec will contain, which tells the agent how those parameters interact.

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 artifact: 'Scaffold a Playwright test from a description using the project's REAL selectors', then enumerates the concrete mechanism (git scan, locator extraction, live cross-check, spec write). It also carves out a distinct second mode ('with `steps` it walks the flow on the live page instead'), so an agent can tell this apart from run-test, validate-selector, or inspect-page without reading 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?

Mode selection is explicit: no `steps` produces a scaffolded spec from discovered selectors; with `steps` the tool walks the flow live, then replays and verifies it. What is missing is routing to siblings — nothing says when to prefer inspect-page or validate-selector, or that run-test is for re-running an existing spec rather than generating one.

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 readOnly/idempotent/closed-world; the description adds the important behavioral fact that the tool only reads the most recent run-test execution, so it is state-dependent on a prior call. It stops short of saying what happens when no run exists or how failures are indexed across runs.

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 scope, followed by a short prerequisite directive. The dense enumeration of returned artifacts is high-value rather than 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 an output schema present, the description need not explain return shapes, yet it usefully summarizes them and flags the run-test dependency. The remaining gap is error-state behavior (no prior run, out-of-range index) and how it relates to overlapping siblings such as suggest-fix.

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%, including the 1-based index and the 'only used to re-read the stored report' note for projectRoot, so the schema carries parameter meaning. The description only adds the contextual fact that the index refers to the last run, which is a marginal gain over 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 and resource ('Analyze one failure from the most recent run-test execution') and enumerates exactly what comes back: message, code frame, expected vs actual, stack trace, network/console errors, failure kind, next steps. The failure-kind taxonomy (assertion/timeout/browser-crash/syntax/config/server-unreachable) makes it unmistakable versus siblings like suggest-fix or bisect-failure.

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?

'Use run-test first' states the prerequisite explicitly, and 'most recent run-test execution' tells the agent which run is targeted. It does not name alternatives or exclusions (e.g., when to prefer suggest-fix or bisect-failure for recurring failures), so it falls short of a full when/when-not statement.

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 non-readOnly, idempotent, non-destructive, so the description doesn't need to re-establish safety. It does add useful behavior beyond that: cancel actually stops the run, waitSeconds blocks, and the final result becomes the last run consumed by get-failure — a cross-tool side effect worth knowing. Missing are the cost of polling/blocking limits and error behavior for an unknown runId.

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 clauses with no filler, and the primary payload (progress/final result) is front-loaded. The telegraphic style ('waitSeconds waits; cancel stops it') and the dangling 'Default: the latest run' cost a bit of clarity.

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?

An output schema exists, so return values needn't be described, and the description still sketches what progress contains (tests done/total, failures so far). What remains thin is the polling/blocking contract and error cases; for a 3-param, 0-required polling tool this is close to 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 only 33% (only waitSeconds is documented in-schema), so the description must compensate — and it does, covering all three parameters: waitSeconds waits, cancel stops the run, and the default (no runId) means the latest run. It does not give the runId format or the origin of the runId, which keeps it below 5.

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?

Names the specific verb/resource (progress or final result of a run-test background run) and scopes it to runs started by the run-test sibling. The relationship to get-failure is stated, so an agent can place it in the workflow. Slightly clipped phrasing ('Progress ... or the final result') keeps it from being a model 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 strongly implied: call this after run-test to poll progress, and the default is the latest run. However, there is no explicit when-to-use/when-not statement and no alternative named for the same job (e.g., versus get-failure directly).

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 (readOnly, idempotent, openWorld), and the description adds genuinely non-obvious traits beyond them: a fresh browser per call with no cookie persistence, locators proven unique on the page, and console messages included in the result. It does not discuss failure modes or limits on page complexity, 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, front-loaded with the core action and output, then the state-isolation caveat, then view modes. Dense but each sentence earns its place; the parenthetical detail in sentence one makes it slightly heavy but not wasteful.

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 19 parameters, nested objects, and no output schema, the description does useful work by summarizing the return shape (locators with role+name priority, CSS selectors, visibility, text, console messages) and warning about browser state isolation. It leaves deeper parameter behavior to the schema, which is reasonable given high coverage, but a few more words on the actions flow would close the 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 description coverage is already 89%, so the schema carries most parameter meaning and the baseline is 3. The description adds context for 'view' ('locators' is the cheapest compact map) and hints at the actions-vs-storageState tradeoff, but does not illuminate the remaining 19 parameters such as har, routes, or timeoutMs beyond what the schema already says.

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 a fresh headless browser') and then enumerates what comes back: elements, unique Playwright locators, CSS selectors, visibility, text, console messages. This is far more specific than a title restatement and clearly separates it from sibling test-authoring tools like validate-selector or generate-e2e-test, though no sibling is named directly.

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 real operating guidance: each call starts clean with no cookies, so either encode the full path in 'actions' or reuse a session via storageState/headers. Also steers view selection ('locators' is the compact map, 'aria' returns the snapshot plus assertion). It stops short of naming explicit alternatives or exclusions among the sibling tools.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the real added value is the disclosed dual strategy: `playwright test --list` with a source-scan fallback when the install or config is broken, plus a reason being reported. That is genuinely useful behavioral context an agent cannot get from the annotations, though it doesn't say what the fallback loses (e.g., whether projects line up).

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, zero waste. The primary behavior is front-loaded and the fallback caveat is packed into a compact second clause without redundant restatement of the name.

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?

An output schema exists, so return values need not be described, and the description still sketches them. Combined with the fallback disclosure it is close to complete; the only soft spot is that multi-config resolution behavior (the `config` index parameter) is left entirely to 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 100%, so every one of the five parameters is already documented in the schema and baseline 3 applies. The description only adds the notion of 'optional filtering' and the returned tuple of fields; it adds no semantics for config, testDir, projectRoot, or the default limit.

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 plus resource ('List the Playwright tests available in the project') and it even enumerates the returned fields (file, line, full title, projects). It is clearly distinguishable in practice from run-test or audit-tests, but it never names a sibling or states that boundary 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 only implied — an agent can infer this is a discovery step before run-test, but the description never says when to reach for it versus audit-tests, diagnose-flaky, or analyze-history. The 'optional filtering' phrase hints at narrowing results without stating when that matters.

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 annotations already declare that this is a non-read-only, non-destructive, non-idempotent operation. The description adds important behavioral context beyond that: CI paths are mapped onto the checkout, traces are found in the unpacked test-results artifact, and the run is recorded in local history with its commit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, moving immediately from the load operation to the supporting behavior. Every clause adds useful information with no repetition or 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 seven-parameter tool with no output schema, the description supplies the key mental model: importing an external run, mapping paths, locating traces, and recording history. It leaves minor gaps around branch/projectRoot and record=false behavior, but the overall context is sufficient.

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 71%, so most parameters are already documented. The description adds value by clarifying the report format (JSON file or blob folder), trace directory discovery, and that the commit is recorded with the run, though it does not cover branch or projectRoot.

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: loading a Playwright run that happened elsewhere, from either a CI JSON report or a folder of blob reports. It also names the downstream tools enabled by it (get-failure, suggest-fix, diagnose-flaky), making its role distinct from run-test.

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 clearly explains when to use this tool: when you have a CI job's JSON report or sharded blob reports and want them treated like a local run. It does not explicitly exclude alternatives or say when not to use it, but the context is sufficiently clear.

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

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

Goes well beyond the annotations by disclosing the actual side effect (failures stop failing run-test and ci), the expiry window (default 14, max 90 days), and persistence in playwright-quarantine.json with a commit instruction. The write-to-file behavior is consistent with readOnlyHint=false and idempotentHint=true, and nothing contradicts destructiveHint=false since removal is scoped and reversible.

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?

About 60 words, front-loaded with the core effect, then per-action semantics, then storage location. Every clause carries information: expiry limits, required fields, persistence file, and the commit reminder.

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 9-parameter, multi-action mutation tool with full schema coverage, an output schema, and annotations, the description supplies the missing pieces: action semantics, expiry behavior, the file that must be committed, and which fields add requires. An agent can call this correctly without further information.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value by stating that add needs owner and reason, which the schema does not enforce (zero required parameters). It also reiterates the days default/max and the add/list/remove action semantics, mapping parameters to actions rather than just restating them.

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 defines a specific verb+resource ('Quarantine flaky tests') and explains precisely what quarantine means: tests keep running and reporting, but failures no longer fail run-test or the ci command. That definition implicitly separates it from siblings like diagnose-flaky or get-failure, though no sibling is named 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?

Each action has a clear role: add requires owner and reason, list shows quarantined and expired entries, remove ends an entry. The context (a known flaky test) is clear, but there is no explicit exclusion such as 'use diagnose-flaky first to confirm flakiness' or advice on when quarantine is inappropriate.

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, but the description supplies the operative detail: it diagnoses missing installs, dead dev servers, syntax errors, crashes and timeouts, kills the process tree on timeout while keeping partial results, emits progress, and persists runs for later analysis. That is materially more than the annotation flags convey and explains exactly why the tool is flagged destructive.

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, front-loaded with the verb/resource and result format, with no filler. The middle sentence is a dense comma-list ('missing installs, dead dev servers, syntax errors, crashes and timeouts') that is information-rich but slightly run-on compared to the crisp opener.

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 an output schema present, return values need not be explained, and annotations cover the safety profile; the description adds failure-mode, background, and persistence behavior. It is essentially complete for invocation, though it never clarifies the fast re-run loop (lastFailed) or the interaction between retries and retryOnFailure, both of which live only in schema text.

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 86%, so parameters are already well documented and the baseline is 3. The description's parameter-related content ('background: true returns a run id', process tree killed past the limit) largely restates the schema text for background and timeoutMs rather than adding new semantics.

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 ('Run the project's Playwright tests') and immediately defines the output shape: stats plus each failure's file:line, kind and message. It is clearly distinguishable from siblings like list-tests (enumeration only) and get-run-status (polling), the latter of which is named explicitly for the background case.

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 when-to-use cues: 'background: true returns a run id for long suites' and 'Runs are recorded for analyze-history', which routes the agent to the right follow-up tool. It does not state exclusions, e.g. that list-tests should be used to discover tests before running a subset, so it stops short of full 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?

Beyond the annotations (idempotent, non-destructive, open-world) it discloses the file write and its default location, the conditional re-login behavior driven by verify, and how secrets are kept out of chat via {{env:...}} and {{totp}}. What is missing is failure/error behavior (e.g., what happens when verify never passes).

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 destination path before the reuse and secret-handling details. Nothing is filler, though the second and third sentences pack several distinct ideas that could be split for scanability.

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 12-parameter tool with nested action/verify objects the description covers the concepts an agent most needs: what is produced, where, reuse semantics, and secret templating; an output schema exists so return values need no explanation. Edge cases such as timeout expiry or directory creation are left implicit.

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 92%, so the baseline is a 3; the description still adds real meaning by explaining the fill-value templating, tying {{totp}} to totpSecretEnv, and prescribing that actions should end with a 'wait' on a signed-in-only element. That is guidance the schema does not encode.

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+resource (log in once and save the session as a storageState file) and states the default destination path, so an agent knows exactly what artifact the tool produces. It also contrasts with the rest of the suite ('for tests and the page tools'), making the tool's role distinct from siblings like inspect-page or run-test.

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 the reuse policy ('if a saved session still passes verify it is reused; expired ones log in again') and its consumer contexts (tests, page tools), which tells an agent when to reach for it. It stops short of explicit exclusions or naming an alternative tool for one-off interactive browsing, so it isn't a full when/when-not map.

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 substantial behavior beyond the annotations: it matches against the DOM at failure time via trace or live URL, returns a diff and confidence, and apply:true writes, re-runs, and reverts if still red. This aligns with destructiveHint=true and clarifies the safety net (auto-revert) and refusal case. It could still state whether a destructive apply requires confirmation or what confidence values mean, but the core mutation semantics are disclosed.

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, front-loaded with the action and scope, then the fix classes, then the write/verify contract and refusal condition. Dense but no redundant clauses; 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?

Given 11 optional parameters, an output schema, and rich annotations, the description covers the essential decision points: what it patches, what it returns, what apply does, and when it refuses. Minor gaps remain around prerequisites for live-URL healing (auth via storageState/headers) and what the confidence score means for deciding to apply.

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 91% schema coverage, the schema already defines url, apply, verify, candidate, and allowExpectationUpdate individually. The description's value is integrative ('apply: true writes it, re-runs the test and reverts if still red'), which connects apply and verify but largely restates what those parameter descriptions say. No additional syntax or conditional-requirement detail (e.g., when storageState/headers are needed) is given.

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 ('Patch a failure from the last run') and enumerates the three fix classes it handles: drifted locator, strict-mode multi-match, and changed copy. This clearly separates it from siblings like get-failure (read the failure) or validate-selector (check a selector).

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?

Establishes the precondition (a failure from the last run) and one explicit exclusion ('Refuses when the element is truly missing (app bug)'). It doesn't name sibling alternatives such as get-failure or validate-selector, so routing is implied 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?

Annotations already declare readOnly/idempotent/openWorld, and the description adds real behavior beyond them: it runs against a live page, counts once after load, and returns a sturdier verified locator per match. Session and header requirements are hinted via storageState/headers but not explained further.

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 purpose, then the key caveat, then a compact list of what is accepted. Every parenthetical example earns its place by defining valid locator forms.

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 an output schema present, the description need not explain return values, and it still summarizes them usefully. For a 15-parameter live-page tool it covers the essentials, though auth expectations and timeout interplay are only partially touched.

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 high (87%), so the baseline is 3, but the description adds meaning by tying waitFor/actions to the late-element case and by spelling out the accepted locator syntax (getByRole, .first(), .filter(), frameLocator()). Other parameters are left 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?

The description opens with a specific verb and resource ('Check a CSS selector, Playwright selector or locator ... on a live page') and enumerates the outputs (validity, match count, sample matches, verified locator). It is clear what the tool does, but it never explicitly distinguishes itself from neighbors like inspect-page or run-test.

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 actionable guidance: 'Counts once after load: use waitFor or actions for late elements,' and notes that actions need exactly 1 match. It stops short of naming an alternative tool or stating when not to use this one.

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