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

Adds substantial context beyond the annotations: the tool creates no order, the returned link contains unencrypted buyer PII and must be shared only with the buyer, payment follows by WhatsApp after the buyer personally confirms, and the tool is stateless (full basket resent, duplicates combined). None of this contradicts readOnlyHint/idempotentHint — a link-generating, non-mutating preview is consistent with them.

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 critical constraints — required fields, ask-before-calling, no order created, statelessness — are front-loaded and a concrete example anchors the shape. It is dense but long, with some redundancy (the buyer-link/PII warning is restated, and prefill rules repeat in both prose and schema), so not a 5.

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?

Covers everything an agent needs for a 5-param nested-object call with no output schema: what is returned (a review link), what it contains, who may receive it, what not to send, how to recover from INVALID_ARGUMENTS, and where prefill data goes. Nothing material is left to inference.

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; the description still earns a bump by warning that Dubai and qty 1 in the example are illustrations rather than defaults, that duplicate IDs must be combined into one line, and that buyer prefill must be nested. It does not add much beyond the already-rich per-field descriptions, so it stops short of 5.

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+resource: prepares a buyer review link for a valid UAE basket, and explicitly says it 'Creates NO order.' It separates itself from the siblings by naming quote_basket (quote first) and search_products (resolve orderable IDs), so an agent can route without opening a 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?

Explicit sequencing ('Quote first and resolve blockers, then send the same complete basket here'), explicit exclusions ('No cart, session or quote ID is accepted'; 'Do not send prices, totals, consent or approval flags'), explicit pre-call collection rules ('Ask the buyer for any missing destination or quantity'), and error handling guidance via missingFields/nextAction on INVALID_ARGUMENTS.

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