GroceryPulse Canada

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint/destructiveHint=false, so the safety profile is covered; the description adds genuinely useful caveats beyond that (chain medians are not branch stock or guaranteed checkout quotes, price dates, source links). The closing read-only sentence partially restates the annotations, which keeps it 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?

Purpose is front-loaded and every sentence conveys a constraint or caveat, but the description is dense and the final read-only clause largely duplicates the annotation hints.

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, and the description does explain what results retain (missing items, exclusions, price dates, scope, per-chain storeLinks), which is solid. Only minor gap is the unexplained stores filter.

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 only 33%, and the description compensates for the items parameter well (each id is one product at its catalogue size; a different size/variant/brand is a different product). However the 'stores' parameter is never mentioned in the description, leaving that filter entirely to the enum, so compensation is incomplete.

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 (compares) and resource (current public chain prices for catalogue item ids in one Canadian city), and explicitly distinguishes itself from plan_grocery_order, which handles free-text lists.

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?

Names the sibling alternative and the condition selecting it, plus states the prerequisite that ids come from get_grocery_catalog and that a lowest-chain recommendation needs fresh full coverage at two eligible chains. An agent knows when this tool applies versus the others.

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 readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds genuinely non-obvious domain context: that coverage is configuration, not live availability, and that a size/variant/brand difference constitutes a distinct product. This meaningfully reduces misinterpretation risk.

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 enumerated content and followed by the two most important caveats. Dense but every clause carries information; the 'checkout eligibility holds: the ids that compare_grocery_list takes' phrasing is slightly convoluted.

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 must explain the return shape, and it does so thoroughly (cities, items with names/ids/referenceSize, units, chains, eligibility holds). It omits nothing critical, though the relationship between 'checkout eligibility holds' and the chain list could be clearer.

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 there is nothing for the description to disambiguate. The schema is empty with additionalProperties false, and per the zero-parameter baseline a 4 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 uses a concrete verb ('Lists') and enumerates the exact resource contents (cities, reference items with ids, quantity units, chains, checkout eligibility holds). It distinguishes itself from compare_grocery_list by noting the ids it returns are the ones that tool consumes, though it says nothing about plan_grocery_order.

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 rather than stated: the note that these are 'the ids that compare_grocery_list takes' hints this is a prerequisite lookup, but there is no explicit 'call this before X' instruction or when-not guidance. The caveat that configured coverage is not current availability is a useful scoping note but not a usage directive.

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 read-only/idempotent/no-destruction, and the description still adds substantial context: the exact/closest/not-tracked classification, per-store totals with coverage and price dates, the strict conditions for declaring a cheapest store, and the 'cheapest for the other lines' partial case. It also explicitly restates the side-effect boundary ('never orders, adds to a cart, saves a list or contacts a store'), which reinforces rather than contradicts the 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?

Purpose and usage trigger are front-loaded in the first sentence, and every clause maps to something the agent needs (inputs, return shape, side-effect boundary). The return-value sentence is very long and run-on, though, packing cheapest-store conditions into one dense block.

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 the description carries the full burden of describing returns, and it does: per-line classifications, per-store totals, cheapest-store logic and its exceptions, per-item links and interpretation notes. Combined with the declared side-effect boundary, an agent has everything needed to call and interpret this 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 description coverage is 100%, so the baseline is 3. The description largely mirrors the schema ('the list as text', 'the city or the first three characters of a postal code', 'optionally, the stores'), adding only the 'up to 60 lines' list-size hint and the quantity/language guidance that the schema already covers.

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 and resource ('Plans a grocery order from a shopping list') and scopes it to 'a covered Canadian city', so the agent knows exactly what the tool produces. It does not name or contrast itself with the siblings compare_grocery_list or get_grocery_catalog, which is the only thing keeping it from a 5.

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 clear triggering conditions: 'Use when a shopper asks where their list is cheapest or wants to buy groceries online.' That is actionable context, but no explicit exclusion ('do not use for X') and no reference to the alternative sibling tools for near-miss cases.

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