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

Annotations already cover read-only, idempotent, non-destructive and closed-world, yet the description still adds substantial non-obvious behavior: payment is handed off to Padel USA's secure Shopify checkout (Shop Pay, cards, PayPal), the delivery address is entered there, and the agent must never request payment details in chat. It also constrains recommendation behavior (no upsell pressure, no repeated suggestions), which no annotation expresses.

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?

Front-loaded with the output contract, then the conversational rules; every sentence carries an instruction. It is dense and runs several behavioral rules together with semicolons, but nothing is redundant padding for a tool with this much policy baked in.

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 correctly spells out the return shape (items, subtotal, shipping options, checkout_url) plus the essentials-suggestion contract, and the annotations carry the safety profile. Gaps are edge cases: empty, expired or unknown cart_id, and where the agent is expected to obtain cart_id are not addressed.

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 only 50% and the description does not reference either parameter — it never mentions cart_id (which is undocumented in the schema too, just a bare string with maxLength 160) or the nested "needs" object it is supposed to be passed on every call. The rich per-field descriptions inside "needs" do the semantic work, so the description neither compensates for the coverage gap nor contradicts it.

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 ("Shows the cart") and enumerates exactly what comes back: items, subtotal, ZIP-based shipping options, and the checkout link. That is enough for an agent to distinguish it from the mutating siblings add_to_cart and update_cart 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?

Prescribes the follow-on flow clearly: show the cart, then offer checkout_url, and treat "essentials" as a single conditional suggestion that is added only on explicit consent. What is missing is routing guidance for the sibling set — nothing says to use update_cart to change quantities or order_help when the shopper has a problem.

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