audit_url

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds valuable context beyond that: the tool navigates to and controls a LIVE external URL, fires hover/click/focus events, scroll-settles the page to trigger IntersectionObserver reveals and play videos, and requires headless chromium. It also discloses that findings are triaged into confirmed | likely-artifact | inconclusive with evidence, which shapes expectations about output quality. No contradiction with 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?

The description is dense but front-loaded, opening with the core mechanism ('render-and-capture audit... renders a LIVE URL') and building through pipeline, checks, output tagging, use cases, and the prerequisite. Every sentence earns its place and no filler is present for a tool of this complexity; it is long, but the richness justifies it.

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 no output schema, the description explains the result shape: findings with confirmed | likely-artifact | inconclusive tags, evidence, severity ranking, and per-capture data. It covers prerequisites, behavior, and use cases for a 9-parameter high-complexity tool with a live-URL dependency. The only small gap is what isn't mentioned — runtime expectations or error behavior — so nothing critical for an agent deciding to call it correctly 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 description coverage is 100%, and every parameter (url, themes, compact, timeoutMs, viewports, interactions, scroll_settle, containerMaxWidth, includeScreenshots) already carries its own meaning and defaults. The description adds pipeline-level color (e.g., why scroll_settle matters, why interactions exist) but does not add per-parameter detail beyond the schema — so the 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?

The description names a specific verb and resource ('render-and-capture audit' of 'a LIVE URL') and describes exactly what the tool does: scroll-settles, fires interactions, captures pixels/DOM, then runs specific rule engines. It explicitly positions itself against the alternative class — 'invisible to HTML-string/geometry audits' — and even names the complete cases it catches, which distinguishes it clearly from the many sibling audit tools.

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 final sentence gives concrete when-to-use guidance ('catches real-world visual nits invisible to HTML-string/geometry audits') and lists examples: cropped images, blank videos, hover white-wash, sliced exports, hidden-on-mobile content. It also states a hard prerequisite (headless chromium). It doesn't name sibling alternatives like audit_page or audit_contrast explicitly as 'use these when...', but the exclusion direction is clear.

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