vaara_verify_receipt

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: two distinct verification steps (signature, evidence binding) plus a conditional third check that depends on whose key is used, including the non-obvious consequence that the audit-trail check is skipped for foreign keys. The notable gap is that it never indicates what the result looks like (valid/invalid verdict, failure mode), and there is no output schema to cover that.

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?

Roughly four sentences, front-loaded with the purpose before the conditional details, and each sentence carries information. It is slightly more verbose than strictly needed — the 'Pass the receipt file's JSON as receipt' instruction largely duplicates the 100%-covered schema — but nothing is wasted or buried.

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 verification tool with a nested-object parameter and no output schema, the description covers the checks performed and the key-dependent branching but says nothing about the shape of the verdict or error results, which the agent must know to interpret a call. Moderate complexity is covered adequately for inputs, incompletely for outcomes.

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 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it explains that 'receipt' takes the receipt file's JSON as-is, and it spells out the semantic consequence of supplying 'public_key_pem' (a foreign issuer's key disables the trail check) rather than merely restating the default.

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 names a specific verb and resource — verify a signed decision receipt — and enumerates exactly what is verified: the signature and the binding between the evidence and what was signed. That is clearly distinct from the sibling tools vaara_check, vaara_intercept, and vaara_report_outcome, none of which share this verify-a-receipt purpose.

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?

Usage is implied rather than stated: an agent can infer this is the tool for validating a receipt it holds, and the description notes that passing another issuer's key skips the trail check. But there is no explicit when-to-use vs. when-to-use-something-else guidance relative to the sibling tools, and no statement of prerequisites beyond the conditional key behavior.

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