verify_claim

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

No annotations are provided, so the description carries the burden. It properly discloses this is a read/verification operation returning evidence, which is useful. However, it doesn't disclose behavioral traits like whether it requires pre-existing capsule state, mutability implications, or any rate-limit/auth constraints, leaving some gaps for a tool with no annotation support.

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?

Two concise sentences with no wasted words. The first sentence delivers the core purpose and listed outputs; the second sentence states the use case trigger. Every element earns its place with clean line wrapping.

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 read/verification tool with 3 simple params and no output schema, the description covers the essential purpose, scope (single claim), what evidence it returns, and the use case trigger. The description is largely adequate; minor gap is the undefined 'consumer' parameter and lack of clarification on relationship between the two required IDs.

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 must compensate for the parameters. The three parameters (capsule_id, claim_id, consumer) are not individually explained semantics-wise in the description beyond the implicit 'one claim' context. The description adds the conceptual link between claim and capsule but doesn't clarify what 'consumer' means or how capsule_id vs claim_id relate specifically.

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 uses a specific verb ('Show') with a clear resource ('supporting and contradicting source evidence') and explicitly scopes it to 'one claim'. It distinguishes itself by naming specific outputs (query fingerprint, time range, deep link) not mentioned by any sibling tools. The final sentence 'Use to challenge an answer' reinforces its distinct use case.

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 provides clear context on when to use this tool ('Use to challenge an answer') and conveys its verification/doubt-checking purpose, which distinguishes it from siblings like drill_down or get_capsule. However, it doesn't explicitly name alternative tools or state when NOT to use it, so it lacks explicit exclusions.

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