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

Annotations only cover idempotentHint and destructiveHint; the description adds the real behavior an agent needs: the document is stored (a side effect), nothing is sent or charged yet, and checkout is the authorization step. The 'reuse draft_token with identical inputs for retries' guidance reinforces the idempotency hint rather than contradicting it, though it doesn't state a retry window or what happens on a mismatched-input reuse.

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, front-loaded with the action and its non-effects before the format and secret-handling details. The fax_number formatting sentence is largely duplicated from the schema, which is dead weight but not enough to derail the structure.

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 usefully names the return values (price, checkout link) and covers the payment/authorization model and input format. It omits the natural follow-up relationship with get_fax_status for status polling, which is the one gap for an agent orchestrating the full fax flow.

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 100%, so all five parameters are already documented, including the fax_number format and the 10 MiB base64 limit. The description restates the fax_number rules verbatim and adds only the 'keep draft_token private' caution, so it lands at the baseline rather than adding new semantic detail.

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 ('Prepare one PDF fax') plus the explicit return payload ('price and Stripe checkout link'), and draws a hard boundary against sending/charging. An agent can tell this apart from get_fax_status without opening either schema.

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?

Clearly frames the two-phase flow: this call stores the document but does not send or charge, and checkout is what authorizes sending to the displayed recipient. It also gives the retry condition ('reuse it with identical inputs'). It never names the sibling get_fax_status as the follow-up for checking delivery, so the routing guidance is incomplete.

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