Cheapest Grocery Basket

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers significant behaviors: out-of-stock items are skipped in favor of in-stock even if dearer, it compares single-store vs cross-store with savings and stop counts, and it discloses the $0.20 USDC cost per call. It does not cover edge cases like invalid zip or no matching stores, but for a query tool this is acceptable.

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 longer than average but every sentence earns its place. It front-loads the core purpose in the first sentence, then adds concrete details about savings, stops, substitutes, and out-of-stock policy, followed by usage context and cost. It is structured and avoids fluff, though it could be tightened slightly without losing value.

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?

Since there is no output schema, the description must convey what the tool returns. It does so: dollar savings, number of stops, per-line substitute costs, and out-of-stock handling. It also states the cost per call. It gives an agent enough to understand the response shape and invoke it correctly. Missing details like error conditions or return format edge cases are minor for this use case.

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 schema description already covers all parameters at 100%, so the baseline is 3. The description adds little beyond the schema: it mentions that items can have quantities and that stores are optional, but these are already in the schema. It does not explain the nuances of the mode parameter or how to handle the JSON array vs comma-separated format beyond what the schema states.

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 names the specific verb 'buy' and resource 'shopping list', and clarifies it provides both the cheapest single store and the cross-store optimum. It explicitly distinguishes itself as 'the one call that answers the whole question', setting it apart from the sibling tools find_product and price_basket.

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 when-to-use guidance: 'Use this as the default for "where should I buy this list today"'. This tells the agent this is the go-to tool for the comprehensive question. However, it does not explicitly mention when NOT to use it or direct to siblings for narrower queries, so it misses the 'alternatives' part of ideal guidance.

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?

No annotations are provided, so the description carries the full burden. It thoroughly details what the tool returns (shelf price, sale status, regular price, package size, per-unit price, stock, link, timestamp), the cost per call, and error behavior for uncovered ZIPs. It does not explicitly state 'read-only' or cover all side effects, but the description strongly implies a non-mutating lookup and adds valuable context like the dual-price nuance.

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?

Although the description is longer than many, every sentence delivers unique information: the core purpose, return fields, a usage example, a clarification about the two price metrics, guidance to sibling tools, and cost. It is front-loaded with the primary action and maintains tight structure without redundancy.

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 must explain return values. It lists every field the caller can expect. It also covers edge cases (uncovered ZIP returns explicit error and is not charged), the cost, and the distinction between sticker price and per-unit value. For a three-parameter tool with no output schema, this is complete.

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 input schema already documents all parameters clearly. The description does not add significant new meaning beyond saying 'q' is in ordinary shopper language, which the schema already states. Since the schema does the heavy lifting, a baseline of 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 and resource: 'Compare a single grocery item across every collected store in a ZIP.' It also explicitly distinguishes itself from siblings by naming them in the usage guidance, so an agent can immediately tell this tool apart from price_basket and cheapest_basket.

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?

Explicitly states when to use: for answering 'who has the cheapest milk near me' for a single item. Clearly says when NOT to use: for a whole shopping list, use price_basket or cheapest_basket instead, and explains why (cost and inability to optimize). The cost disclosure is also included.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that delivery fees and minimums are not collected yet and are returned as null, that it returns the oldest price to indicate staleness, and that it costs $0.05 USDC per call. This is substantial behavioral context beyond what a schema would provide, though it does not cover rate limits or authentication specifics.

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 well-structured and efficient: it starts with the primary purpose, lists the key return values, gives usage guidance, and ends with cost. Every sentence contributes necessary information without redundancy or fluff. It is front-loaded and easily scannable.

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?

Given there is no output schema, the description does a good job enumerating what the agent can expect in the response (line items, totals, missing items, completeness, stock flags, oldest price). It also covers the delivery fee null behavior and pricing. It does not mention error cases (e.g., no stores found) or pagination, but for a pricing tool these are minor gaps.

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. However, the description adds meaningful context beyond the schema: it explains how the 'mode' parameter behaves (delivery fees are null), provides a concrete example of quantity formatting ('milk x2') and notes that a JSON array is also accepted. This extra detail helps the agent correctly encode inputs, raising it above baseline.

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 clearly states the tool's function: it prices a complete shopping list at every store in a ZIP code and returns per-store line items, subtotals, and missing items. This is a specific verb (price) and resource (shopping list across stores), and it distinguishes itself from the sibling cheapest_basket by emphasizing per-store results and completeness rather than just the cheapest single option.

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 description gives a clear usage context: 'Use this when the shopper will make one trip and wants to know where the whole list is cheapest.' This is explicit guidance, though it does not mention when to avoid it or explicitly compare to alternatives like cheapest_basket. The cost mention also serves as a practical consideration, but the differentiation between tools is not fully spelled out.

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