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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the agent knows it's a safe read. The description goes far beyond by disclosing that findings are samples: 'the pages listed are never the complete affected set and no field reports how many were left out.' It explains the analyzed flag as a false-positive guard ('empty findings are an absence of evidence rather than a clean result'), and details the coverage field semantics ('proven' vs 'partial'). It also clarifies that gainedId is the only confirmation of a fix. 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 long but every sentence earns its place: it front-loads the core purpose in the first sentence, then layers critical caveats (sampling, analyzed flag) and a procedural workflow. It uses paragraph breaks for logical grouping. While it could be tightened, it avoids fluff and repetition, so the length is justified by the tool's complexity.

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?

Given the tool has no output schema and the operation is a read of a complex graph-analysis result, the description covers all necessary aspects: what findings represent, how to interpret counts and samples, the meaning of the analyzed field, the exact workflow to verify fixes, and the semantics of coverage. There are no gaps that would leave an agent uncertain about how to invoke the tool correctly or interpret its results.

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 input schema already provides full descriptions for both parameters (run_id and website_id), achieving 100% coverage. The tool description adds valuable context beyond the schema: it explains the default selection behavior for run_id (latest audit that stored at least one entity, and why), warns about audit runs being passed over, and clarifies the precedence between run_id and website_id. This enriches the schema, though the schema already carries the core semantics.

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 opens with a precise statement of what the tool returns: 'schema/entity-* rule verdicts for an audit', specifying the resource (audit), the nature of the data (verdicts on entity graph problems), and the granularity (findings across the whole site). It explicitly differentiates itself from re-deriving problems manually and names the alternative tool list_entities for the full affected set, which distinguishes it from siblings.

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 gives clear when-to-use guidance: 'Use this instead of re-deriving the problems from the graph yourself.' It also provides a complete fix-and-verify loop with explicit steps (call list_entities with problem='no-id', assign @id, re-run audit with run_audit, then call compare_entities and check gainedId). It further explains when NOT to rely on findings (sampled lists) and when to check the analyzed flag to interpret empty results. This is explicit and actionable.

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