Crawl and audit multiple pages

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

Annotations declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, so the mutation/idempotency profile is already structured. The description adds real context beyond that: each page is fetched once and shared across checks, a polite delay is applied, and the sitemap-index-aware seeding behavior. It stops short of describing rate-limit thresholds or auth needs, and the disk-writing behavior of the html output lives only in the schema.

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 action, then the seeding strategy, then the aggregate list — every clause carries information. It is a dense single paragraph rather than a bloated one, though the aggregate enumeration could be tightened.

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?

There is no output schema, so the description usefully enumerates what comes back (site-wide issues, broken links, redirect chains, duplicate titles/metas, orphan sitemap URLs, per-page issues) and even explains the >50% threshold for site-wide classification. Missing only the baseline-diff behavior, which is left to the schema.

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 all five parameters are already documented in the schema (including output enum semantics and output_path defaults). The description only echoes max_pages and the crawl seed URL, adding no syntax or format detail beyond the structured fields. 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 ('Crawl a site ... and audit up to max_pages pages') and enumerates the aggregate outputs, so the scope is unmistakable. It does not explicitly distinguish itself from the sibling seo_full_audit, which is presumably also a multi-page audit, so sibling differentiation is implied rather than stated.

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 explains the internal mechanism (sitemap seeding with link-following fallback) but never says when to reach for this tool versus seo_full_audit or the single-purpose check_* siblings. No prerequisites, no exclusions, no decision rule for the agent.

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