Israeli supermarket prices (Foodiepedia)

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it returns the total in every chain that sells all items, the cheapest chain, the saving versus the most expensive, chains missing items, and the best split between two chains. This gives the agent a clear picture of the output's richness without needing an output schema. It doesn't mention edge cases like empty results or error handling, but the annotations cover the safety aspects.

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 a single, well-structured sentence that front-loads the core purpose ('Given a shopping list... returns the total in every chain') and then enumerates the specific outputs. Every clause adds value: the input format, the comparison scope, the cheapest chain, the saving, missing items, and the two-chain split. No wasted words.

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 tool with one parameter, no output schema, and rich annotations, the description is quite complete. It tells the agent what input is expected (barcodes and quantities) and what outputs to expect (totals, cheapest, saving, missing items, best split). It doesn't specify the exact format of the return value, but without an output schema, the description's enumeration of outputs is sufficient for an agent to understand the tool's capability. A 4 is fair because it could mention how the 'best split' is calculated or whether the result is sorted, but 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 description coverage is 0%, so the description must compensate. The description explains that the 'items' parameter is a shopping list of barcodes and quantities, which directly maps to the schema's structure. It adds meaning by clarifying that the list is used for basket-level comparison, not just individual price lookup. However, it doesn't detail the qty default or constraints, but those are already in the schema. With 0% coverage, the description does a good job of bridging the gap.

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 ('returns') and clearly identifies the resource ('shopping list') and the operation's scope: comparing totals across chains, identifying the cheapest, the saving versus the most expensive, missing items, and best split between two chains. It distinguishes itself from siblings like get_product_prices and rank_chains by focusing on a basket-level comparison rather than individual product prices or chain ranking.

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 implies when to use this tool: when you have a shopping list of barcodes and quantities and want to compare totals across chains. It doesn't explicitly state when not to use it or name alternatives, but the context signals and sibling names (get_product_prices, rank_chains) make the use case clear. A 4 is appropriate because the context is clear but exclusions are not explicitly 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 mark the tool as read-only, idempotent, and non-destructive. The description adds genuinely useful behavioral context beyond that: results are today's shelf prices, sorted cheapest-first, include check times, and there is a caveat about summary.suspect when presenting savings.

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 with no wasted words. The core result is front-loaded, followed by the optional parameter and a safety caveat; every sentence adds operational 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?

There is no output schema, so the description compensates by indicating key response content: per-chain prices, check times, cheapest-first ordering, and summary.suspect semantics. It does not detail the exact response shape or not-found behavior, but for a simple two-parameter read tool this is a minor gap.

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?

With 0% schema description coverage, the description carries the parameter explanation: barcode identifies the product, and include_history controls whether recorded price changes are returned. It explains the semantic role of both parameters, while the barcode format is left to the schema's pattern constraint.

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 action ('shelf price... in each Israeli supermarket chain') on a concrete resource ('one product by barcode'), sorted cheapest-first. This clearly distinguishes it from sibling tools like compare_basket, rank_chains, and search_products by its single-product, cross-chain scope.

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 clearly scopes the tool to a single barcode across tracked chains and explains when to set include_history. It does not explicitly name alternatives or state when not to use it, so the 'vs alternatives' guidance is mostly implied rather than explicit.

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 cover safety with readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate those. It adds useful methodological context about ranking over a common product set, but it does not disclose output format, data source, or averaging details.

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?

A single focused sentence that front-loads the action and subject, then adds the ranking criterion and scope. No filler or redundant wording.

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 low-complexity, parameterless tool with strong annotations, the description is nearly complete: it explains what is ranked, on what basis, and over what product set. The main gap is the lack of explicit output format, but the ranking intent is clear enough for an agent to invoke 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?

The tool has zero parameters and the schema is empty with 100% coverage, so there is no parameter burden for the description to carry. Baseline 4 applies because there is nothing to document.

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 ('Ranks') with a clear resource ('Israeli supermarket chains') and a precise basis ('how much more they charge than the cheapest price'). The phrase 'over a common set of identical products' further distinguishes this chain-level comparison from product- or basket-level sibling tools.

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 implies a use case: call this when you need a chain-level ranking, not individual product prices or basket comparisons. However, it never explicitly says when to prefer this tool over compare_basket, get_product_prices, or search_products, nor does it name any exclusions.

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 mark the tool read-only, idempotent, and non-destructive. The description adds that results are barcodes with lowest/highest shelf price across tracked chains, which explains the cross-chain aggregation. This is useful beyond the annotations, though the exact result structure isn't detailed.

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, front-loaded purpose, concrete examples, and a routing directive. No filler and every sentence earns its place.

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 simple two-parameter lookup with strong annotations, the key usage context and downstream integration are covered. The main omission is a fuller return shape, but since no output schema exists, the description gives enough for an agent to know what it will get.

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 only documents query, and coverage is 50%. The description adds Hebrew inputs and concrete examples for query, which helps, but the limit parameter remains undocumented by both schema and description; its behavior is only inferable from its name/default.

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 search behavior (find by Hebrew name, brand, or barcode), the resource (Israeli supermarket products), and the return shape (barcodes with low/high shelf prices). It is clearly distinguished from the sibling price/basket/ranking tools.

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 tells the agent to feed the resulting barcode into get_product_prices or compare_basket, establishing this tool as the product-lookup entry point. It does not explicitly contrast with rank_chains or state a negative case, but the routing is clear enough.

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