Fetch and verify receipt

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real behavioral detail beyond them: the four verification questions, that 'not_answered_by_this_root is a real answer', that result fields are passed through unaltered, and that a genesis fetched in the same call is never the trust root. Return-shape disclosure partially overlaps the output schema, keeping this from a 5.

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?

Purpose and the trust-root enumeration are front-loaded, but the dense single-paragraph form with heavily nested parentheticals (the chain object grammar inline) makes it harder to parse than the content warrants. Every sentence carries technical weight, so little is wasted, but structure could be cleaner.

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 9-parameter tool with a nested trust union and an output schema, the description covers the hard parts (trust-root selection, chain vs byte roots, result composition) thoroughly. Minor elements like baseUrl and receiptUrl sourcing are left to the schema, which is acceptable given 89% coverage and an existing output schema.

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 89%, so the schema already carries most parameter meaning (baseline 3). The description adds above-schema value by tying payload+entryId to the attribution answer and enumerating the trust-root shapes and the chain path, helping the agent map inputs to verification outcomes.

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 compound verb+resource ('Fetch a receipt ... and verify it') and explicitly frames the fetch as being like fetch_receipt, letting an agent distinguish it from the plain fetch sibling. The scope is unambiguous: retrieve then cryptographically verify under a supplied trust root.

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 framing '(as fetch_receipt) and verify' implicitly routes agents who only want a raw receipt to fetch_receipt, and it gives a live condition ('Supply payload bytes and the entry id to have attribution answered'). It stops short of an explicit when-not statement, so it is strong context rather than full routing guidance.

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