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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: only the last 5 runs are kept per site, issue results are capped at 50 per call and continue via offset, and the summary includes deltas since the previous run.

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?

Dense but front-loaded: the default no-argument behavior comes first, then each mode in turn, then the run-retention caveat. It is a single run-on paragraph, which costs a little scannability, but every clause carries information.

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 10 optional parameters and no output schema, the description carries the burden well by describing what each mode returns (pages by status and clicks, issues with counts/importance/examples, changes since last run) and how to page through results. Missing only the meaning of the remaining bare parameters and any authentication/rate context.

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 70%, and the description compensates where the schema is bare: match is "part of an address", status is "like 404 or 3xx", issue is an id from the summary, page is a single address, and run refers to entries under runs_kept. It also documents the 50-per-call limit tied to limit/offset, though it does not explain the 200 cap.

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 ("Read a site audit that site_audit made") and immediately signals the producer/consumer split with the sibling site_audit. The four invocation modes (summary, issue, page, match/status) make it unmistakable what the tool returns in each case.

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?

Gives explicit conditional routing: no extra arguments returns the latest-run summary, issue returns the pages behind one issue, page returns everything about one address, match/status lists pages, and run selects an earlier run. It does not compare itself against neighboring read tools (page_audit, crawl_report, health_report), so it stops short of full alternative guidance.

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