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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: purchases happen off-app on a website and the result includes that link, which prevents the agent from promising an in-app purchase flow. The annotated idempotentHint=false for a pure listing is odd, but the description neither repeats nor contradicts it.

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 short sentences: the first defines the operation and its payload, the second gives the calling context, the third states the off-app purchasing constraint. Nothing is repeated and the most decision-relevant content is front-loaded.

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?

Output schema and annotations carry the structured burden, and the description covers purpose, use case, and the purchase-channel caveat. Minor omissions: no mention of currency or whether pricing is per-pack or region-dependent, which matters for a pricing question.

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?

There are zero parameters, so the baseline is 4 and there is no parameter meaning for the description to supply. The description instead explains the shape of the returning records ('how many letters each adds', 'what it costs', 'the link'), which is useful even though the output schema exists.

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 gives a specific verb and resource ('List the letter packs') and immediately defines the payload ('how many letters each adds and what it costs'), so an agent knows exactly what it gets back without opening the output schema. It does not, however, explicitly differentiate itself from pricing-related siblings such as quote_and_preview_letter, which also surfaces costs.

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?

'Use this to answer questions about pack sizes or pricing' states a clear triggering context, and 'Packs are bought on the Letter IRL website, not in this app' sets an important boundary on what the agent may do next. There is no explicit exclusion naming the sibling that handles per-letter quoting, which is the main gap.

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