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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's added value is the determinism claim, 'No LLM is used by the server', and the 'correlation is never presented as causation' constraint on the output — meaningful trust signals about how results should be interpreted. It still omits idempotency and behavior when evidence is thin or missing.

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 lead sentence that front-loads the verb and the full output contract, followed by two short clauses on determinism and causal discipline. No filler and no repetition of schema content.

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 explained, and the description still frames what the analysis yields and its epistemic limits. The remaining gap is lifecycle placement — nothing states that evidence must be collected first or what happens if the investigation has none.

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

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

Schema description coverage is 100%, with both parameters documented including the pattern and the note that investigationId comes from start_investigation, so the baseline of 3 applies. The description adds nothing about additionalContext's role in symptom matching, which the schema already covers anyway.

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 operation (deterministic analysis) on a specific resource (recorded evidence in an investigation) and enumerates the produced artifacts: observed facts, ranked root causes with supporting/contradicting evidence, confidence, reproduction status, and discriminating experiments. That output list effectively separates it from collect_evidence and generate_bug_report, 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?

Usage is only implied: the phrase 'recorded evidence' and the investigationId sourced from start_investigation suggest this runs after evidence collection. There is no explicit when-to-use, no prerequisite statement (e.g. requires at least one collect_evidence call), and no named alternative.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false; the description goes beyond them by scoping the blast radius precisely (browser context and egress proxy only) and reassuring that evidence and artifacts survive until retention ends. That is exactly the extra context an agent needs before a non-read operation, though it omits what happens on a re-close or an already-closed investigation.

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 filler, with the resource scope front-loaded and the durability caveat immediately after. 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 values need no explanation, and the description covers scope and data-retention behavior for a mutation tool. Minor gaps remain around preconditions (must the investigation be running?) and side effects on in-flight siblings such as collect_evidence, but nothing essential to a correct call is missing.

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

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

Schema coverage is 100% and the single parameter already documents that the id comes from start_investigation, including its format pattern. The description adds nothing about the parameter, so the schema does all the work and 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 ('Closes') plus the exact resources affected — the browser context and egress proxy of an investigation — which an agent can distinguish from start_investigation and the analyze/generate siblings. It stops short of explicitly naming a sibling it complements or replaces, so it is clear but not maximally differentiated.

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 implied trigger (an investigation is finished and its live resources should be released) is inferable from the name and the retention sentence, but the description never states when to call it, whether the investigation must be active, or what to do instead if you only want to stop one resource. Usage remains inferred rather than guided.

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

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

Annotations only cover read-only and closed-world safety; the description goes well beyond by disclosing that secrets are redacted in URLs and messages, that request/response bodies are never stored, and that page-derived text is untrusted and must not be acted upon. That last point is a genuinely non-obvious behavioral risk an agent could not get from structured fields.

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

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

The return shape is front-loaded in the first clause, followed by filtering/pagination, then the redaction and prompt-injection caveats. Each clause carries distinct information, though the security sentences could be compressed slightly without loss.

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 further explanation, and the schema fully documents the five inputs; the description's remaining job is safety framing, which it does well via the redaction and untrusted-content warnings. Minor gap: captureScreenshot's side effect is not acknowledged anywhere in the prose.

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 every parameter including captureScreenshot and limit is already documented in the schema. The description restates the category filter and sinceSeq pagination without adding format or interaction details, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Returns sanitized evidence items and a compact timeline for an investigation'), making the output shape immediately legible. It does not name or distinguish itself from 'analyze_evidence', so sibling differentiation is left to the agent's inference from names alone.

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

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

The description implies retrieval of raw evidence as opposed to analysis, and mentions optional category filtering and sinceSeq pagination, but never states when to prefer this over analyze_evidence or why one would collect before analyzing. Usage is implied by the retrieval wording 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?

Annotations already declare it as a non-destructive, idempotent write; the description adds value beyond them by disclosing the concrete side effect (writes report.json into the artifacts directory) and the report's section structure. It does not state prerequisites such as whether investigation or evidence steps must be complete first, which keeps it off 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?

One front-loaded sentence with the verb and deliverable first, then a parenthetical enumerating report contents. The content list is long but each item conveys what the report contains, so little is wasted; it borders on over-enumeration.

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 no explanation, and the description still characterizes the report's contents and output location well. The remaining gap is lifecycle placement — no hint about which prior investigation steps must have run — but overall it is sufficient to invoke correctly.

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

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

Schema coverage is 100% and the single parameter already carries a description pointing back to start_investigation, so the schema does the heavy lifting. The tool description adds nothing about the investigationId (format, source, or requirement), so baseline 3 applies.

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

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

States a specific verb and resource ('Builds a structured JSON bug report') and names the artifact produced ('report.json in the artifacts directory'), which clearly separates it from generate_regression_test. It does not explicitly name a sibling it is not, but the deliverable is unambiguous.

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

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

There is no explicit statement of when to call this (e.g., after evidence collection/analysis and before close_investigation) or when not to. Usage is only implied by the lifecycle ordering of sibling tools and by the investigationId parameter.

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

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

With readOnlyHint and openWorldHint already declared, the description adds genuinely new behavioural facts: the code is returned for review, is never executed by the server, and assumptions are listed explicitly. That is exactly the context an agent needs about side effects and output shape beyond the annotations.

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

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

Three tight sentences, front-loaded with the artifact produced, then the safety guarantee, then the assumption disclosure. No sentence restates the title or wastes tokens.

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 unnecessary, and the description covers the non-execution guarantee and assumption listing. It stops short of explaining whether the investigation must be in a particular state or what a failed generation looks like, which are the remaining gaps.

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

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

Schema coverage is 50%: investigationId is documented in the schema and reinforced only indirectly by 'from the investigation', while testName is never mentioned in the description and relies entirely on its pattern/maxLength constraints. With half the parameters undocumented in prose, a 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 artifact: generates a Playwright TypeScript test from the investigation, scoped to the observable behaviour behind the reported symptom. The artifact type clearly separates it from siblings like generate_bug_report, but the description never names or contrasts an alternative, so sibling differentiation is left implicit.

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

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

The phrase 'from the investigation' implies the tool is used after evidence gathering and before reporting, and the schema's investigationId ties it to start_investigation, but the description never states when to use this versus generate_bug_report or reproduce_issue, and offers no exclusions or prerequisites in prose.

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: annotations only say readOnly=false, destructive=false, openWorld=true, whereas the description discloses the allowlist mechanism, the JavaScript prohibition, and the blocking policy for state-changing HTTP and destructive-looking controls. That is exactly the kind of policy context an agent needs before submitting steps.

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

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

Three sentences, no filler, and the core behavior is front-loaded before the constraint sentences. Every sentence carries distinct information (capability, sandboxing limit, safety blocking).

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 an output schema exists and annotations cover the read/write profile, the description covers the key behavioral risk surface. Minor gaps: it does not mention that execution stops at the first failure by default (continueOnFailure) nor the 50-step cap, both of which affect how an agent should build a step list.

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

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

Schema description coverage is 100% and the discriminated-union step schema fully enumerates the actions and their shapes. Naming the action list in prose is mildly reinforcing but adds no semantics the schema does not already carry; 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 ('Executes an ordered list of allowlisted browser actions') plus the side effect it produces ('records the outcome of every step'). The enumerated action set (navigate, click, fill, select, reload, waitFor, screenshot) makes it immediately distinguishable from the investigation/evidence/report siblings.

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?

Makes the operating envelope explicit — no arbitrary JavaScript, state-changing requests and destructive clicks are blocked unless operator-enabled — which tells the agent when this tool will and will not work. It does not explicitly route against siblings (e.g., 'use after start_investigation, before generate_bug_report'), leaving that to the investigationId param description.

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

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

Goes well beyond annotations: discloses the execution sandbox ('isolated, policy-restricted Chromium context'), enumerates the evidence channels recorded, states the return value, and flags that page-derived text is untrusted and must not be followed as instructions. The annotations only say openWorld/non-idempotent/non-destructive; the prompt-injection warning is a genuinely high-value disclosure that annotations cannot convey.

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

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

Three tight sentences, front-loaded with what the tool does, then the return value, then the configuration hint, then a security caveat. Every sentence carries distinct information with no filler.

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

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

With 8 parameters including nested objects, plus an output schema and annotations, the description covers action, scope, return, and safety. What's missing is lifecycle guidance — duration/blocking behavior and the expected next step (e.g., collect_evidence) for an investigation-started session.

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

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

Schema coverage is 75%, so the baseline is 3. The description's selector advice largely restates the schema's own 'watch' description ('needed to observe flicker and placeholder bugs'), and undocumented items like the waitUntil enum values, viewport, and maxDurationSeconds semantics get no added explanation.

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 and resource: opens targetUrl in an isolated, policy-restricted Chromium context and begins recording named evidence channels. The addition of 'Returns an investigation id' and the selector guidance make it clearly distinguishable from collect_evidence or reproduce_issue, though the description never names those siblings explicitly.

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

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

'Use watch.loading / watch.content selectors for flicker or placeholder bugs' is real conditional guidance, but it only covers one parameter's configuration. There is no statement of when to call this instead of reproduce_issue, collect_evidence, or what prerequisite state is needed.

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