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

Annotations only declare readOnlyHint=false and destructiveHint=true; the description adds substantive behavior: consent must be echoed from the quote, the purchase can complete itself after payment in the embedded path, and the alternative returns a checkout_url. It does not state what is charged, whether the purchase is reversible, or what happens on partial failure — meaningful for a destructive=true tool.

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 disclosure obligation is stated three separate times ('First show...', 'pass what they affirmed', 'Before any purchase, show...'), and the eleven verbatim disclosure bullets duplicate content the tool tells the agent to read from the quote's required_disclosures anyway. The gathering-order paragraph is well structured, but roughly half the text is repetition that crowds out the flow-critical instructions.

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 three-parameter, branch-heavy purchase tool with no output schema, the description covers the full lifecycle: data gathering, disclosure display, consent echoing, and both terminal responses. Annotations handle the safety profile, so the remaining burden is workflow and it is met.

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 coverage is 100%, so the baseline is 3, but the description earns above baseline by tying consent to what the consumer actually affirmed and explaining that disclosure_set_id and disclosure_text_sha256 must be echoed from the quote. It also clarifies billing_interval is the interval the consumer chose, not an arbitrary selection.

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 opening verb+resource ('Buy a complete quote') is specific and immediately distinguishable from the create_quote and complete_purchase siblings. It also names the two mutually exclusive outcomes (requires_payment vs requires_hosted_checkout), so an agent knows the tool's return shape without opening the 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?

Strong sequencing guidance: check for declarations pages first, route to read_declarations_page and create_quote, and only then purchase. The conditions selecting the embedded-checkout vs hosted-checkout path are stated explicitly. The gap is that the overlapping sibling complete_purchase is never named or contrasted, leaving the agent to infer which tool finishes a purchase.

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