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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the pagination contract (cursor/nextCursor), the fact that evidence is only a sample and can be truncated, and the follow-up needed when it is. It does not discuss rate limits or ordering of findings, keeping it short of a 5.

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 first sentence is dense but front-loaded and earns its place. The sentence about evidence truncation is grammatically mangled ('list_audit_rows with subject finding and the finding’s key pages all evidence.rowCount rows'), which costs clarity, and the get_audit note is placed after rather than before the routing advice.

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 carries the burden of explaining return contents, and it does so concretely (severity, affected item counts, whyItMatters, recommendedFix, evidence sample). Only the limit/result-count behavior is left unaddressed, which is a minor gap for a read-only listing tool.

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 75%, with runId, cursor and projectId already documented in the schema. The description's 'Page with cursor and nextCursor' largely restates that, and it says nothing about the limit parameter (default 25, max 100), which is undocumented in both places. 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 (list every finding of a finished SEO Audit) and enumerates what each finding carries: severity, number/type of affected items, whyItMatters, recommendedFix, and an evidence sample. It also implicitly distinguishes itself from get_audit by noting that get_audit only contains the top findings.

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?

It states the precondition (a finished audit) and explicitly routes the agent to siblings: get_audit for the top findings, and list_audit_rows with subject='finding' plus the key pages when evidence.truncated is true. Conditions and alternatives are both stated, not inferred.

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