Dry-run QA flow

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

The annotations indicate readOnlyHint=false (potentially mutating) and openWorldHint=true (external interaction). The description adds the behavioral detail of a 'fresh headless Chromium session', which clarifies that each call is isolated and state is not shared. It also states the report is returned. This is useful beyond the annotations, though it does not mention side effects, rate limits, or the 'dry-run' semantics 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?

The description is a single, well-formed sentence that packs the core action, environment, and output. It is front-loaded with the verb and resource, and contains no redundant words. It is an excellent example of concise writing.

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

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

Given the tool's complexity (a QA runner with multiple action types), the description is terse. It mentions the fresh session and the report, but does not clarify the 'dry-run' nature (no permanent side effects on external systems), any prerequisites (e.g., URL accessibility, authentication), or constraints (e.g., maximum number of actions). The existence of an output schema reduces the need to describe the return format, but more operational context would be helpful for correct invocation.

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

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

Schema description coverage is 50% – the 'url' parameter is described, but 'actions' has no top-level description. The tool description only says 'role-based browser actions and assertions', which is vague and does not explain the structure or expected format of the actions array. The nested item schemas do provide per-element descriptions, but the description does not add enough to compensate for the missing top-level parameter description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Run'), resource ('role-based browser actions and assertions'), and environment ('fresh headless Chromium session'), plus the expected outcome ('step-by-step pass/fail report'). It differentiates from the sibling tools by mentioning the QA execution context, but does not explicitly name them or contrast itself, so it falls short of the model example (get_calls) which explicitly named its sibling.

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

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

There is no guidance on when to use this tool versus its siblings (scan_dom_accessibility, compile_playwright_spec). The description explains what it does but does not provide any conditions or exclusions. An agent would have to infer the context from the name and the described functionality, which is insufficient.

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