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

Annotations already declare a non-read-only, non-destructive, open-world mutation, and the description adds genuine context beyond that: the return payload (each added product with resulting quantity, failures, cart total), plus the unavailable/replacements flow telling the agent to surface substitutions to the user. That is exactly the kind of post-call behavior an agent cannot infer from annotations.

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 action, then sourcing, batching, return shape, edge case, alternative, and boundary — each sentence carries distinct information with no restatement of the schema or annotations.

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 explains the return values and the failure/replacement path, and it flags the ordering boundary. For a one-parameter nested-array mutation tool, an agent has everything needed to call and interpret it correctly.

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 adds value by stating the per-call cap of 20 and the aggregate semantics of the items array (all requested products in one call). It does not restate quantity defaults or formats, which the schema already covers, 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?

Specific verb ('Add') plus resource ('products to the user's Picnic shopping cart') with explicit scope (one or more, max 20 in one call). It distinguishes itself from the two nearest siblings by naming set_cart_quantity for quantity changes and implying remove_from_cart's counterpart role.

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?

Gives prerequisites (get product ids from search_products first), batching guidance (put all requested products in one call), an explicit alternative ('make it 4' → set_cart_quantity), and a boundary ('This does not place an order'). When-to-use is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine behavioral context the annotations lack: the result includes per-product availability with a reason and drugstore-style replacement suggestions, which tells the agent to expect partial-unavailability handling rather than a plain list.

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?

Two sentences, front-loaded with the core purpose, followed by the edge-case return details. Every clause (quantity, price, total, delivery window, unavailable reason, replacements) carries information about the payload.

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 parameters and no output schema, the description bears the burden of explaining the return shape, and it does so thoroughly: line items, totals, delivery window, and the unavailable/replacements cases. Nothing an agent needs to interpret the response is missing.

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?

The tool takes zero parameters, so the schema has nothing to explain and the baseline is 4. The description correctly implies the cart is scoped to the authenticated user with no arguments needed.

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 ('Show the user's Picnic shopping cart') and enumerates exactly what is returned: products, quantity, price, total, delivery window, plus unavailable/replacements. This makes it clearly distinguishable from the mutating cart siblings (add_to_cart, remove_from_cart, set_cart_quantity) without opening any 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?

The read-only framing implies when to use it (to inspect cart state before mutating or checking out), but there is no explicit guidance such as 'call this after add_to_cart' or when to prefer a sibling. Usage is inferred from the verb and the sibling list rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description's added value is the pagination/expansion behavior: without a date it returns the first two days in full plus just the dates of other days. That is exactly the kind of behavior an agent could not infer from the annotations, though return shape/naming is left implicit.

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?

Four short sentences, each earning its place: purpose, default behavior, parameter usage, and next step. The default-behavior detail is front-loaded right after the purpose.

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 single optional-parameter read tool with annotations covering safety and no output schema, the description supplies everything needed to call it correctly in both modes and to route to the correct follow-up tool.

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% with a format pattern, so the baseline is 3. The description adds real semantic constraint beyond the schema: the date should come from the list returned by a previous call, and omission is the default expansion mode.

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 ('List the delivery slots') plus its scope ('for the cart'), making it easy to tell apart from siblings like get_cart or select_delivery_slot.

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?

Explains both invocation modes (omit date vs. pass a date from the returned list) and names the follow-up tool with its trigger ('use select_delivery_slot once the user picked a slot'). It doesn't state prerequisites explicitly (e.g., that a cart must already exist), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds real behavioral context instead: default mode returns aisles with only a few products each, whereas an aisleId returns all of the user's products in that aisle, and results carry ids usable with add_to_cart. It stops short of describing result size, ordering, or pagination behavior.

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?

Three sentences, all load-bearing, with the core purpose front-loaded and the mode behavior and downstream caveat following in logical order. Nothing repeats the schema or annotations.

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 single-optional-parameter read tool with no output schema, the description covers purpose, both modes, and result usability well enough to call correctly. The remaining gap is a lack of detail on return shape beyond 'a few products each' and on how large a full aisle listing can be.

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% and already documents aisleId's pattern and 'leave out for the overview'. The description still adds meaning by contrasting what the output looks like in each mode and by clarifying that the aisleId value itself originates from a prior get_favorites call, which the schema states only briefly.

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?

The description uses a specific verb and resource ('List the products the user buys at Picnic, per aisle') and scopes it to purchase history, which separates it from catalog-oriented siblings like search_products and get_product. An agent can identify this as the favorites/usual-groceries tool 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?

It names concrete usage scenarios ('what do I usually buy?', 'my usual groceries') and explains both operating modes: the no-argument overview versus passing an aisleId for a full aisle listing. It also gives downstream guidance ('add only the ones the user asks for'), so an agent knows both when to call it and how to act on results.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by listing the data payload (ingredients, allergens, nutrition, storage, promotion, price), which tells an agent what it can answer after calling. No mention of error behavior, but the read-only nature plus the payload listing is sufficient.

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?

Two tight sentences, front-loaded with the purpose and payload, followed by the id sourcing. Zero wasted clauses.

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?

There is no output schema, so enumerating the returned fields is exactly the compensating information needed. Combined with the explicit id-source chain, an agent can call this correctly with no further context.

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 description coverage is 100% and the single productId param has a pattern plus an example (s1004201). The description only repeats the sourcing of the id from search_products or get_cart, adding no syntax or format detail beyond the schema, so baseline 3 is appropriate.

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?

The description opens with a specific verb+resource (get the details of a Picnic product) and enumerates the content returned – ingredients, allergens, nutrition, storage, promotion, price. That enumeration clearly separates it from siblings like search_products or get_cart, which return lists rather than a single product's full detail.

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?

It gives a concrete use case (questions such as whether a product contains gluten) and an explicit prerequisite chain: obtain the id from search_products or get_cart. The only gap is it doesn't state when-not-to-use or what happens if the id is invalid.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: the result shape at each drill-down level ("sections ... with a few products and promotions each") and the fact that returned products carry add_to_cart ids. It does not mention result size limits, pagination, or how current the "this week" data is.

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?

Three tight sentences, front-loaded with the core purpose, followed by each invocation mode in the order an agent would use them. No filler and no repetition of the schema.

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 carries the burden of describing returns, and it does so at a high level for all three modes plus the product id handoff to add_to_cart. Slightly incomplete on how many sections/products come back and whether results are exhaustive per section.

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 baseline is 3, but the description goes further by explaining the dependency chain: the overview yields section titles and promotionIds that feed the next call, and omitting both yields the overview. That relational meaning is not in the schema.

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 with scope: "List what is on promotion at Picnic this week." It then distinguishes three distinct result modes (overview, section, single promotion), which makes clear this is a promotions browser rather than a product search, separate from siblings like search_products or get_product.

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?

Gives explicit per-mode usage: no input for the section overview, a section title for all products in it, a promotionId for the products of one promotion. It also hints at the downstream workflow ("Products have ids for add_to_cart"). It stops short of naming alternatives or exclusions, e.g. when to prefer search_products over browsing promotions.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by disclosing the return payload ('quantity left in the cart and the cart total'), telling the agent no follow-up get_cart call is needed after a partial removal.

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?

Three short sentences with the mutation stated first, the data prerequisite second, and the return value last. Nothing is redundant and every clause carries information an agent needs.

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 compensates by describing the returned quantity and cart total. It is nearly complete for a 2-param mutation; the only gap is what happens when quantity exceeds what is in the cart.

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 both productId (pattern, example) and quantity (default, min/max) are already fully documented. The description only reinforces the productId source, which the schema also states, so it adds no meaning beyond the schema.

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 ('Remove a product from the user's Picnic shopping cart'), which clearly separates it from add_to_cart and set_cart_quantity by implication. It stops short of naming the sibling it differs from, so an agent must infer that set_cart_quantity is the absolute-overwrite alternative.

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?

'Get the product id from get_cart' gives an explicit prerequisite and data source, which is genuine routing guidance. However, there is no statement of when to prefer this over set_cart_quantity or add_to_cart, and no exclusion/edge-case guidance (e.g. removing more than present).

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

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

Annotations only state readOnly/openWorld; the description adds the meaningful behavior: the result partitions into bestMatch vs choices, with an explicit action rule for each, and that bestMatch is usually a previously purchased item. It omits what happens on zero results or any pagination/rate considerations.

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?

Four tight sentences: purpose, input constraint, then the two result cases in order of likelihood, then the flag definition. No filler and the most decision-relevant content is front-loaded.

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 carries the return-value burden and does so by explaining bestMatch, choices, and boughtBefore. The empty-result case is left implicit, which is the main remaining gap for an open-world search.

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 baseline is 3, but the description adds real semantics beyond the schema: the query must be Dutch and a short product name rather than a free-form phrase. That measurably improves match quality for the caller.

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 ('Search the Picnic supermarket for a product') plus the downstream payoff ('get its id for add_to_cart'), which distinguishes it from get_product, which takes an id rather than a query. An agent can pick this tool 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?

Gives explicit branching instructions for the two result shapes: use bestMatch directly, but ask the user when choices comes back. Also constrains input ('Dutch, short product name'). It does not name sibling alternatives such as get_product or get_favorites, so it falls short of a 5.

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

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

Adds value beyond annotations by disclosing the return content (selected delivery window and cart total) and the key behavioral limit that no order is placed. Idempotency and non-destructiveness are already covered by annotations, so only the omission of what happens when an existing slot is re-selected keeps this from a 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?

Three short sentences, each with a distinct job: what it does, how to source the argument, and what it returns plus what it does not do. Scoping constraint is front-loaded and there is no filler.

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 a single required parameter, no nested objects, and no output schema, the description supplies everything needed: valid input source, precondition, return values, and the boundary against order placement.

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% and the parameter already carries a description, so the baseline is 3. The description earns extra credit by restating the provenance constraint on slotId (must come from get_delivery_slots), which prevents fabricated IDs.

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 object ('Choose when the cart is delivered') and explicitly bounds the scope with 'This does not place an order,' which separates it from a checkout tool. The reference to get_delivery_slots makes the sibling relationship unambiguous.

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?

Gives an explicit precondition: only use a slotId from get_delivery_slots, after the user picked the slot. That names the alternative tool to call first and the user-confirmation condition, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=true, so the safety profile is established. The description adds useful behavioral detail beyond annotations: quantity 0 removes the product, and the call returns the quantity now in the cart plus the cart total. It does not mention auth or rate limits, but the annotation coverage lowers that burden.

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 description is three tight sentences that front-load the purpose, then explain the key quantity-0 behavior and productId source, then state the return values. Every sentence adds relevant information and there is no filler.

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?

Although there is no output schema, the description explicitly says it returns the quantity now in the cart and the cart total. The input schema covers parameter bounds and formats, and annotations cover the safety profile, so an agent has enough to invoke and interpret the tool correctly.

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 description coverage is 100%, and both parameters are fully documented in the input schema, including the productId pattern and the quantity 0-removal behavior. The description largely repeats that schema information (productId source and 0 removal) without adding new syntax or meaning, so the baseline 3 is appropriate.

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?

The description states a specific verb, resource, and scope: setting the absolute quantity of a product in the user's Picnic cart. The example "make it 3" and the note that 0 removes the product distinguish it from add_to_cart and remove_from_cart, which adjust quantity incrementally rather than setting it directly.

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?

It gives a clear usage context ("when the user says 'make it 3'") and states the prerequisite for obtaining productId from get_cart or search_products. It does not explicitly contrast when to use this versus add_to_cart/remove_from_cart or state when not to use it, so it falls short of full alternative routing.

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