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

Goes beyond the annotations by disclosing merge semantics ('Earlier topics are kept; a new answer replaces the same topic'), a validation rule, and a downstream effect ('A public-only choice allows a partial report without further access requests'). These clarify the destructiveHint=true/idempotentHint=true profile, though permission/auth requirements are only implied by the schema.

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?

Five sentences, all information-bearing, with the core purpose front-loaded. Slightly dense but no filler; the merge-behavior and side-effect sentences each earn their place.

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?

For a destructive, nested-schema mutation with an output schema present, the description covers the key semantics (topic merge behavior, source requirement, report side effect) without needing to restate return values. Remaining gaps—auth via audit_key and revision/request_id mechanics—are handled by the schema descriptions.

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?

With 67% schema coverage, the description usefully explains the two most semantically complex parameters: audit_scope's choice between continuing the investigation and public_only, and availability_expectation's expected/unexpected meaning. It adds real meaning beyond the schema for these nested params, though url/audit_id/revision/request_id are left to the schema.

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 ('Saves answers about one audited component to the audit') and names the concrete topics being written. However, it does not differentiate itself from nearby siblings like record_audit_runtime or submit_findings, so an agent must still infer the boundary between them.

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?

Provides implied usage through constraints ('Both must have source human_reported') and the consequence of the public-only choice, but never states when to use this tool versus an alternative, nor any when-not condition. Usage is inferable rather than explicit.

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