preview_fix

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

Despite no annotations, the description fully discloses behavioral traits: read-only, no rendering, no writing, returns specific verdict categories (pass, idempotent, blocked, manual), and includes before/after. It clarifies the scope (structural safety gate, not pixel/visual). No contradictions.

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 concise and front-loaded with the purpose. Each sentence adds value, though it could be slightly tightened. It is well-organized with important details upfront.

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 no output schema, the description fully explains what the tool returns (verdict categories and before/after). It covers safety, action, and outcome. No gaps remain for effective use.

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?

The only parameter 'fix' has a schema description stating it must include url and edit, which adds clarity beyond the schema's type definition. This helps an agent understand the required structure.

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 tool is a read-only dry-run of a single fix proposal against current HTML. It specifies the action (preview), the resource (fix proposal), and the context (page's HTML). It distinguishes itself from siblings like propose_fixes and audit_site by focusing on validation before applying edits.

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 when to use (after propose_fixes to validate a fix) by referring to the object returned by propose_fixes. It also explicitly states the tool never modifies the site and is a structural safety gate. However, it does not provide explicit when-not-to-use scenarios or alternative tools.

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