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

Annotations declare readOnlyHint=false and destructiveHint=false; the description adds real value with the AUDITOR token requirement and the separation-of-duties rule. However, the word 'read-only' sits uneasily next to a readOnlyHint of false — it evidently refers to the external lookup, not the tool's own write of a verdict, and that distinction is never spelled out. It also does not say what recording a verdict does to the claim's state or whether a verdict can be revised.

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?

Three short sentences, front-loaded with the authorization prefix, then the action, then the constraint. Nothing is padded or repeated. The telegraphic 'AUDITOR tokens:' opener is dense but efficient for a scanning agent.

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?

An output schema exists, so return values need not be described, and the description covers who may call, what is checked, and the conflict-of-interest rule. The remaining gap is failure behavior — what happens when claim_id is unknown or the external_ref is unreachable — which matters for a verification 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 description coverage is 0%, so the description has to carry the load, and it partially does: it explains that verdict is VERIFIED/REFUTED and that evidence captures 'how you checked'. That is meaningful guidance the schema does not contain. It says nothing about claim_id beyond the implicit reference, and never indicates whether evidence is expected or optional.

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 concrete verb pair and resource: check a change claim at its external_ref and record VERIFIED or REFUTED. The parenthetical ('the commit exists, the PR state') clarifies what the check inspects. It does not explicitly name report_change_claim as the counterpart that creates claims, so differentiation from that sibling is implied rather than stated.

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?

Gives a clear gating condition ('AUDITOR tokens') and an explicit exclusion ('The reporter cannot verify its own claim'), which tells the agent when it may not use this tool. It stops short of naming the alternative path for non-auditor agents, so routing to a sibling is left to inference.

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