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

Annotations already declare this as a read-only, idempotent, non-destructive, non-open-world operation. The description adds that it returns public details, the akay.ie link, and ordering instructions, but much of that is also covered by the output schema, so it adds only moderate behavioral context beyond structured fields.

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?

The description is a single well-formed sentence that front-loads the key action and resource. There is no filler, and it communicates the essential scope immediately.

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?

Given one required parameter, rich annotations, and an output schema, the description is largely complete for a read-only single-resource lookup. Minor gaps remain around how to obtain the offer_id and how closed offers are handled, but nothing critical 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 is fully described in the schema as accepting an offer_id from search results or the akay.ie offer URL. The description restates that the tool accepts an offer_id or URL but does not add syntax, format, or validation details beyond the schema.

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: retrieve full public details of one open offer by offer_id or URL. It implicitly distinguishes a single-offer lookup from the sibling search_offers tool, but it does not explicitly name or contrast with any alternative.

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: call this when you already have an offer_id or URL. However, the description does not explicitly say to use search_offers first to obtain an offer_id, nor does it state when not to use this tool or what happens for closed/nonexistent offers.

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