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

Annotations declare destructive=true and idempotent=true, and the description corroborates and enriches these: 0 removes the line, re-setting the same quantity changes nothing (matching idempotentHint), failed edits leave the basket unchanged, and nothing is bought or charged. The effective-id and error-handling behaviors go well beyond what the annotations convey.

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?

Dense but front-loaded: core semantics of quantity come first, then edge cases, then return value, then sibling routing. Every sentence carries a distinct behavioral fact and none is redundant.

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 mutation tool with an output schema, it covers everything needed: argument semantics, failure modes, idempotency, side-effect absence, and alternatives. Return-value detail is kept brief because the output schema carries it.

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%, but the description adds non-obvious semantics the schema does not: quantity is the new total rather than an increment, 0 removes the line, id comes from view_basket/add_to_basket, and basket_id is only for hosts that do not identify the user. This genuinely disambiguates the set-vs-add ambiguity an agent would otherwise guess at.

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 (change quantity of a product) on a specific resource (teas.co.uk basket) and distinguishes itself from add_to_basket and view_basket by name. An agent can route correctly 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?

Explicit routing is given at the end: use add_to_basket to add new products, view_basket to inspect first. It also states the preconditions (no basket at all returns an error) and edge behavior (unknown id, parcel-limit breach), so when-not cases are covered.

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