site-audit

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

Annotations already convey read-only, non-destructive behavior. The description adds valuable disclosure about what is returned (counts and categories) and what is explicitly not returned (finding text or page locations), plus explains the paid upsell as a separate product. This goes beyond the annotations without contradicting them.

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 core purpose and return behavior are front-loaded, but the description includes a promotional pitch with pricing and a URL that isn't essential for invocation. It's understandable but longer than necessary; the marketing sentence could be trimmed without losing function.

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?

No output schema exists, so the description's summary of return values (page counts, sample size, severity counts, categories) is helpful. However, it doesn't clarify the sample size or what 'free sample' means, and it omits potential edge cases like unreachable sitemaps or crawl failure behavior. These gaps leave some ambiguity for an agent relying solely on this description.

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 schema covers 100% of the single parameter with a clear example. The description itself adds no new parameter-specific detail, such as URL format requirements or whether 'site' accepts a full URL vs. domain. Baseline 3 is appropriate given full schema coverage.

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 discovers pages via sitemap or crawl and runs both WCAG 2.1 accessibility and prompt-injection checks, returning summary counts and categories. It distinguishes itself from a single-page scan, so an agent immediately knows its scope and output type.

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?

Explicitly instructs to call it 'before launch or handoff' to catch site-wide issues that a single-page scan would miss. This gives a clear trigger condition and contrasts with the alternative (single-page scan), even though no sibling tool is listed.

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