Israeli supermarket prices (Foodiepedia)

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds substantial behavioral context beyond that: it requires an API key (with exact authorization formats), explains the no-key teaser and trial offer, states the data source and update cadence, and mandates citation and checked_at reporting. This is exemplary disclosure.

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 adds necessary operational information: what it returns, data provenance, authentication, fallback behavior, and attribution requirements. It is front-loaded with the core function before moving to supporting details, so the structure is effective for an agent scanning for relevance.

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 fully enumerates the return value categories and adds all contextual requirements (API key, teaser, citation, checked_at, data source, update frequency). For a tool with one parameter and no output schema, this definition leaves no critical gaps an agent would need to invoke 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 has 0% description coverage for its single parameter, but the description compensates by explaining 'shopping list (barcodes and quantities)', mapping directly to the 'items' array and its barcode/qty fields. It also clarifies the domain meaning of the parameter, which goes beyond the raw 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?

The description uses a specific verb ('returns') and names multiple concrete outputs: total per chain, cheapest chain, saving versus most expensive, chains missing items, and best split. It clearly identifies the resource (shopping list of barcodes and quantities) and distinguishes itself from siblings by focusing on basket-level comparison across chains.

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 clear context: use this when you have a shopping list of barcodes and want to find the cheapest chain and potential savings. It does not explicitly name sibling alternatives or state when not to use it, but the input format and purpose are unambiguous enough to guide selection.

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, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: API key requirement, teaser response without a key, summary.suspect caveat about presenting savings, obligation to cite foodiepedia.co.il and checked_at, and twice-daily data updates. These go far beyond the structured 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?

The description is longer than minimal but each sentence carries distinct operational value: purpose, benefit, data source, auth, edge behavior, and citation requirements. It is front-loaded with the core function and avoids filler, though the auth and suspect warnings add length.

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 only 2 parameters and no output schema, the description gives everything an agent needs to call the tool correctly: what the response contains (cheapest-first prices, checked_at, unit prices, history), ordering, authentication prerequisites, and handling of suspicious price gaps. Nothing critical 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?

Schema description coverage is 0%, so the description bears the burden of explaining parameters. It explicitly ties barcode to one product ('by barcode') and clarifies include_history as 'recorded price changes'. This adds real meaning over the schema's raw property names, though it does not elaborate on defaults or value formats.

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 identifies a specific verb and resource: 'Today's shelf price of one product (by barcode) in every Israeli supermarket chain we track, cheapest first'. This distinguishes it from siblings like compare_basket and rank_chains by focusing on a single product's price across chains. It also includes output details such as checked_at and unit prices, making the purpose unmistakable.

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 provides clear context for when to use the tool: to show where a product is cheapest and how much more other chains charge, saving the user money. It does not explicitly name alternative sibling tools or state when not to use them, so it stops short of full exclusion guidance. Still, the intended use case is obvious.

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?

While annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds critical behavioral context: authentication requirements, the teaser response when unauthenticated, trial key details, and mandatory citation with checked_at. This significantly exceeds the annotation coverage.

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 dense but well-structured, front-loading the core ranking purpose before adding data source, auth, and citation details. Each sentence carries essential information, though a bit more brevity would improve it.

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 zero-parameter, read-only tool with annotations covering safety, the description covers data provenance, update frequency, authentication, and usage expectations. It does not specify the exact output format, but the simple ranking output and lack of output schema make this 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?

The input schema has zero parameters, so the baseline of 4 applies. There are no parameter semantics to explain, and the description appropriately focuses on behavior and context rather than inventing parameter meaning.

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') and resource ('Israeli supermarket chains') with a clear comparative metric ('how much more they charge than the cheapest price'). It also states the exact question it answers, distinguishing it from siblings like compare_basket, get_product_prices, and search_products.

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 phrase 'Answers "which supermarket is cheapest in Israel?"' provides clear context for when to invoke this tool. It also mentions prerequisites (API key) and behavior without one, though it does not explicitly name alternative tools or exclusion cases.

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?

Beyond the readOnly/idempotent annotations, the description discloses data provenance (legally mandated transparency files), update cadence (twice a day), deduplication by barcode, free-tier request limits, and the mandatory citation with checked_at. This is exactly the behavioral context annotations cannot express. No contradiction with 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?

The description is dense but organized: capability, return fields, data source, tier limits, downstream routing, and citation requirement. It front-loads the most important fact ('FREE, no key needed') and each sentence earns its place; only slight redundancy with the schema's limit note prevents a 5.

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 fully compensates by listing the returned fields (barcodes, size, chain count, cheapest price/chain), freshness, tier differences, and attribution obligations. An agent has everything needed to call the tool correctly and interpret results.

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 adds value by giving concrete Hebrew examples for query and by clarifying that limit's real-world cap is 5 on the free tier and 25 with a key, which the schema already hints at but the description makes actionable.

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 action ('Find grocery products sold in Israeli supermarkets') and a precise query scope (Hebrew name, brand, or barcode), with concrete examples. It further distinguishes itself from siblings by pointing to get_product_prices and compare_basket as follow-up tools for per-chain pricing, so an agent can clearly separate search from price retrieval.

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 explicitly states when to move on to alternatives: 'Use the barcode with get_product_prices or compare_basket to show the user every chain's price and where their whole list is cheapest.' It also explains the free vs API-key tier difference, which informs whether a query will need a key for more than 5 matches.

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