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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it documents the authorization scope (any API key on the account that made the lookup), an eventual-consistency window ('saved a few seconds after the lookup'), and cost behavior ('free; does not cost a lookup'). It also discloses the salient shape of the returned payload including the SHA-256 digest, which matters for verification use cases.

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 tight sentences with zero filler: identity and contents first, then access scope, then timing and cost caveats. Every clause carries information an agent would otherwise have to guess.

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?

With no output schema, the description discharges the burden by enumerating the returned fields including the SHA-256; it also covers auth, timing lag, and cost. For a one-parameter read tool, nothing an agent needs to invoke it correctly is missing.

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?

The single parameter has full schema coverage with an example format ('rcpt_0123abcd...'), so the schema carries the semantics. The description only restates that lookup is keyed by receipt_id and adds no format, provenance, or error-handling detail beyond it. Baseline 3 applies when schema coverage is 100%.

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 verb and resource ('fetch the saved copy of an earlier lookup') and enumerates exactly what the receipt contains: timestamp, endpoint, identifier, exact response, and SHA-256. This is unmistakably distinct from lookup_carrier (which performs a new lookup) and from get_history.

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?

Establishes clear context: it retrieves a prior lookup by id, is readable by any API key on the originating account, and is free ('does not cost a lookup') — which implicitly steers the agent away from re-running lookup_carrier. It never names an alternative sibling explicitly, so the when-not guidance is implied rather than stated.

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