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

The description states the primary effect (recording a signal) and explicitly says it never changes the audit's scores, verdict, or stored report, which aligns with the non-destructive annotation. It does not address idempotency, duplicate handling, or side effects like notifications, and the key requirement is mentioned without detail on validation or failure behavior.

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 compact, with three sentences each covering distinct aspects: key requirement, core purpose, and non-modifying nature. The all-caps and URL add mild noise, but overall it is efficiently structured.

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's complexity (required key, finding identification methods, nested evidence), the description covers prerequisites, identification, and effect. It does not specify the response or output, but since no output schema exists, this is acceptable. It is sufficiently complete for an agent to decide when and how to call it.

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 descriptions already cover parameters well, and the description adds meaningful context: findingKey is preferred over dimension+title, 'from the digest' clarifies provenance, and evidence is tied to the repo. This goes beyond a mere restatement of 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?

The description states precisely what the tool does: it records a dispute or confirmation of a prior audit finding, backed by repo evidence. It clearly identifies the two stances and the object (finding), distinguishing it from sibling tools like verify_fix or report_loop.

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 tells the user they need a key and where to mint one, and explains that the tool is a signal for owner triage, not a modifier of the audit. It also clarifies how to identify the finding (findingKey or dimension+title). However, it does not explicitly contrast with alternatives, though the use case is inherently distinct.

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