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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false. The description adds value beyond them: it discloses cost ('Free', 'costs nothing'), states repeated calls are safe and normal, names the precondition of a completed audit, and describes the return shape ('what comes back is written to be read out'). What it does not cover is failure behavior when the audit is absent or still running, which keeps 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?

Front-loaded with the routing rule before the detail, and every sentence carries information. It is long, and the per-topic enumeration plus the relay instructions make it dense, but the length is justified by the eight mutually ambiguous topic values rather than padding.

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 a two-parameter schema, no output schema, and no nested objects, the description supplies exactly what is missing: the meaning of each topic, the prerequisite, the cost profile, and guidance on how to relay the returned content. Nothing an agent needs to call it correctly is absent.

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 50% and audit_id carries no description at all. The description compensates heavily on the one enum parameter, expanding each of the eight topic values into the specific questions it answers, which is meaning an agent cannot derive from the bare enum list.

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+resource+scope: it answers one question from a completed audit by returning that part in full. It explicitly contrasts itself with 'the entire report' and with the agent's own summary, so an agent can place it against get_audit and get_audit_report without opening sibling schemas.

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?

Explicit trigger ('THIS IS THE TOOL FOR ANY FOLLOW-UP QUESTION about a page you have already audited'), an explicit prohibition ('Never answer a question about an audited page from your own summary of it'), a stated prerequisite ('Needs a completed audit'), and a per-topic routing table that tells the agent which topic answers which kind of question.

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