Albert Heijn: Update Order Item

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

Annotations already declare readOnlyHint=false and destructiveHint=true. The description goes beyond them by disclosing the required order state (which is not obvious) and by spelling out that quantity=0 destroys the line item. It stops short of return values or any confirmation of what the mutation yields, so 4 rather than 5.

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 core action, then prerequisites, then alternatives; every sentence carries routing or state information. The delivery-slot parenthetical is slightly heavy but is doing real explanatory work.

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, but for a two-parameter mutation with annotations covering the destructive profile, the description supplies everything else needed: prerequisites, id provenance, removal semantics, and alternative tools.

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 and both parameters are already documented in the schema (including 'quantity 0 removes the item'). The description adds genuine value by telling the agent where product_id comes from (ah_search_products or ah_get_cart), which the schema does not.

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 precise verb+resource+scope: 'Set the quantity of a product in the active Albert Heijn delivery order.' It names the siblings it is not (ah_add_to_shopping_list for pre-order collection, ah_remove_from_cart as an alternative), so an agent can route correctly without opening schemas.

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 prerequisites (an order must exist, created by choosing a delivery slot), explicit alternatives with the condition that selects each (ah_add_to_shopping_list before an order exists; ah_remove_from_cart instead of quantity=0), and a stated special-value convention.

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