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

Annotations declare readOnlyHint=false and destructiveHint=true, which is counterintuitive for a 'get' tool; the description earns credit by explaining why — it 'may automatically correct stale content-product selections when a publisher's content requirements have changed' — so the mutation risk is disclosed. It also documents the failure envelope and error-handling contract. It does not say whether corrections are reversible or what side effects they carry.

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 primary purpose, then the mutation caveat, then the error-handling contract — a sensible order. Slightly long on error-handling prose for a read-mostly tool, but every sentence carries actionable content.

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?

No output schema exists, yet the description adequately describes the return shape (billing details presence, payment methods) and the failure shape ({ ok: false, error }). The main completeness gap is the undocumented discount/promo parameters, which leaves an agent guessing about capabilities the tool evidently has.

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 40%. The two required analytics parameters (context, llm_model) are documented in the schema, but promoCode, adminFixedDiscountName, and adminFixedDiscountAmount have no description anywhere, and the description never mentions them. It is genuinely surprising that a read-cart tool accepts admin discount amounts, and nothing explains when those should be supplied.

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 ('Get the current state of the user's shopping cart') plus the concrete contents returned (billing details presence, available payment methods). An agent can distinguish it from add-to-cart, update-cart, clear-cart, and get-order without inspecting 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?

Usage is implied (read cart state before checkout) and the description gives solid guidance on handling the `{ ok: false, error }` path, including an explicit 'do not retry blindly' exclusion. However, it never says when to prefer this over update-cart or get-order, nor any prerequisite ordering relative to place-order.

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