audit_url

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

Goes well beyond the annotations: discloses hard bounds (8 assets, 2MB each, 1 request/second shared limiter, default 10s timeouts, 50-item finding cap), redirect/origin resolution rules, severity sorting that guarantees `worst` survives the cap, and a graceful-degradation contract where perf returns {error} without suppressing the static scan. Nothing here conflicts with readOnlyHint=true, openWorldHint=true, idempotentHint=false, destructiveHint=false.

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-loaded with the core purpose and mechanism, then layers limits, redirect rules, and degradation semantics. It is dense and long, but nearly every clause carries operational information; only the repeated bounding statements (timeouts/limits) shade toward redundancy.

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 tool with no output schema, it covers failure modes, caps, origin rules, and degradation well enough to call safely. The response shape itself is only partially implied (`perf` with {error}, a findings list capped at 50), so an agent still cannot fully predict the return envelope.

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 baseline is 3. The description only echoes timeout behaviour ('default 10s timeouts') and never mentions the viewport enum or its geometry, so it adds little meaning beyond what the schema already provides.

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 ('Audit any live page') plus a precise scope: runtime frame/long-task/layout-thrash measurement over raw CDP with an installed Chrome/Edge, and static animation anti-pattern scanning over HTML and same-origin CSS/JS. The framing 'as evidence, not a grade' and the '(no playwright)' qualifier separate it from sibling capture/analysis tools without needing to name them.

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 'evidence, not a grade' framing plus the runtime-vs-static split gives a clear signal for when this tool is the right choice, and the closing sentence sets an authorisation constraint ('audit only URLs you are authorised to inspect') and a personal/non-commercial scope. It stops short of explicitly naming alternatives among capture_live_site, analyze_page_structure, or analyze_bundle for exclusion cases.

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