audit_page

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

The description does add behavioral context: it returns pass/fail per check with fix instructions, and it explains how containerMaxWidth changes the max-width check from a generic 1200px heuristic to a token-aware divergence check. However, annotations state readOnlyHint=false, idempotentHint=false, and destructiveHint=true, while the description's 'audit' language implies a non-mutating analysis and never discusses side effects that would justify the destructive mismatch. This is a nontrivial gap, but not a direct contradiction.

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 dense but appropriately so for a tool with 9 parameters and five audit categories. Every clause earns its place, and the purpose and the main parameter special-case are front-loaded. It is a single long sentence rather than a scannable structure with bullets or paragraph breaks, so slightly less structured than ideal.

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?

The description gives a decent overview of what the audit covers and roughly what it returns, but there is no output schema and the return-value description is incomplete—it does not mention score, grade, screenshots, passes list, or fix_priority, though some of this is inferable from the compact parameter description. It also does not state whether at least one of url or html is needed and does not address the many sibling audit tools that might be the better choice.

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 (89%) and the schema already describes each parameter, so the baseline is 3. The description nonetheless adds semantic value for containerMaxWidth by explaining how it affects the heuristic, what 'token-aware' means, and the fact that it flags containers that are either too narrow or too wide. This goes beyond the schema's basic 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 opens with a clear verb and resource: 'Audit HTML/CSS against Raven's design quality standards,' then enumerates several concrete check domains, so an agent can easily recognize this is a broad page-level design audit rather than a single-issue audit. However, it never explicitly contrasts itself with the many specialized audit_* siblings (e.g., audit_typography, audit_contrast, audit_url), so it is clear but not fully 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 description does not say when to prefer this tool over an audit_* sibling or when not to use it. There is no alternative route or exclusionary context. The only conditional usage advice is about the optional containerMaxWidth parameter, which is parameter guidance, not tool-selection guidance.

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