Verify an order's 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 real work: it explains the trust semantics ('a valid signature proves Agoreum made the claim') and that the named transaction, not the signature, is what proves payment. It omits failure modes (missing receipt, key rotation, unverifiable order) and never explicitly confirms the call is side-effect free, but 'fetch' plus local key verification strongly implies read-only.

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 tight sentences with the action and the verification target front-loaded. The closing clause 'the result says which to check' is slightly cryptic but points the reader at the interpretation guidance rather than wasting words.

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?

There is no output schema and no annotations, so the description is the only source of truth about the response – yet it only vaguely says 'the result says which to check' without describing the fields returned (valid/invalid, transaction reference). For a verification tool whose entire value is the response, that is a notable gap, though the input side is adequately covered.

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 0% – the single order_id parameter has format and pattern constraints but no textual description. The description compensates partially by indicating the ID must reference a *completed* order, which is meaningful scoping information not in the schema, but it adds nothing about ID format or lookup behavior.

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 compound action (fetch the signed receipt, verify against Agoreum's published keys) on a specific resource tied to a completed order. This clearly separates it from generic siblings like agoreum_get_order or agoreum_settle_order, though it never names an alternative explicitly.

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 by 'a completed order's receipt', which signals the order must already be completed before calling. There is no explicit when-to-use guidance, no statement of what to do when verification fails, and no pointer to a sibling for the non-verifying case.

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