WizStore — Israeli supermarket prices

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context the annotations cannot: the index baseline (100 = national median basket), the direction of the scale (below 100 is cheaper), and the ordering and inclusion of store counts.

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 sentence with no filler; the key interpretation rule (100 = national median, below 100 cheaper) is embedded where it is needed and the ordering/content facts follow immediately. Nothing could be removed without losing meaning.

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 carry the return shape, and it does: index values, their scale, ordering, and the presence of store counts. It does not state how many chains are returned or whether the list can be empty, but for a zero-argument aggregation tool this is nearly 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?

There are zero parameters, so per the baseline a 4 is appropriate. The description implicitly confirms the call takes no filters by saying the index covers every chain WizStore covers, which matches the empty input 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 states a specific resource (price index per retail chain) and adds the scale semantics and ordering, so an agent knows exactly what it returns. It does not explicitly distinguish itself from the similar sibling compare_basket_by_chain, so it falls short of the top mark.

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 only implied: the description makes clear this is a cross-chain overview (cheapest first, with store counts), which suggests when it is useful, but there is no explicit when-to-use or when-to-prefer-alternatives guidance versus siblings like compare_basket_by_chain or cheapest_stores_in_city.

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 read-only/idempotent/non-destructive/closed-world, so the burden is low; the description still adds real behavior: ranking methodology, the 60%/85% eligibility thresholds, the meaning of city_rank 1, and the presence of not_ranked_reason for excluded stores.

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?

One dense sentence that is front-loaded with the core purpose and then the ranking rules. Every clause carries information, though the em-dash run-on is heavy for a single sentence.

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 compensates by explaining city_rank and not_ranked_reason, which an agent would otherwise not know. The remaining gap is the undocumented limit parameter and any result-count/pagination behavior.

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 only 50%: city is documented in both places, but limit has no description anywhere. The description usefully confirms Hebrew/English/slug city formats (slug is not in the schema examples) but says nothing about limit or default/max behavior.

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+resource with unusual precision: cheapest supermarket branches in a city, ranked by a fixed-basket shelf-price total. It distinguishes itself from sibling price tools (chain_price_index, compare_basket_by_chain) by being city-scoped store ranking, though it never names an alternative explicitly.

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 only implied — an agent can infer this is the tool for 'cheapest stores in city X', but the description gives no when-to-use statement, no exclusions, and no routing to compare_basket_by_chain or chain_price_index, which are plausible confusions.

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/non-destructive, so safety is covered. The description adds real behavioral context: definitions of shelf_total, effective_total and club_total, the ranking rule (chains selling every item first, by shelf_total), and the caveat that effective/club are best-case across branches rather than one real branch.

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?

Dense but front-loaded: the core purpose and the city exclusion come first, then total definitions, then the sibling pointer. It is longer than minimal, but nearly every clause carries distinct semantic value; the parenthetical 'a typical branch' aside is the only trim candidate.

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 describe return semantics, and it does: per-chain totals, item counts, missing items, and ranking order. An agent has enough to interpret and use the result without guessing.

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 schema already documents the single 'items' parameter with format, limits and an example. The description adds no parameter-level detail, so baseline 3 is appropriate — it neither compensates nor detracts.

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 (compare) and resource (shopping list across retail chains) and immediately scopes it with 'no city needed'. It clearly distinguishes itself from price_shopping_list, which is the sibling that handles city-level branches.

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 tells the agent when this is the right tool (chain-level comparison, no city) and names the alternative for the other case: 'for real branches in one city use price_shopping_list'. The routing condition 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the 10%-below-median threshold, the national-or-single-chain mode, and club_only as a payload attribute — all relevant to interpreting results.

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?

One dense sentence that front-loads the deal definition before enumerating payload fields. No waste, though the field list at the end stacks several concepts and could be marginally tighter.

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 usefully enumerates returned fields (deal_price per unit, shelf price, national median, club_only, promotion text, end date), which is exactly the burden a no-output-schema tool places on prose. Only the limit parameter's behavior is left unspecified.

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 only 50% (limit has no description). The description compensates by explaining that results can be national or restricted to one chain, which clarifies the optional chain parameter and the default mode when it is omitted. It does not explain limit's pagination/cap behavior.

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+resource ('Today's strongest supermarket deals') and nails down the inclusion criterion — promotions at least 10% below national median shelf price. This is far more precise than siblings like chain_price_index or cheapest_stores_in_city, and an agent can tell it apart 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 scoping rule (national vs. one chain) implies when the tool applies, but there is no explicit guidance on when to choose it over compare_basket_by_chain or get_product_prices. Usage is inferable from the deal criterion 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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds real substance beyond them: the exact price aggregates returned, the distinction between open promotions and club-only promotions, a 90-day history window, and the purpose of the `page` field for quoting. It does not cover failure behavior (e.g., product not sold anywhere) or response shape/pagination, keeping it short of 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?

One dense, front-loaded sentence that enumerates only output-relevant facts; no filler or restatement of the name. It is somewhat list-heavy and would read better split, but every clause carries information.

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 and no annotations describing returns, the description correctly carries the return-value burden by naming each aggregate and the `page` link. It is nearly sufficient, missing only edge-case behavior (product absent from all chains) and any note on chain/currency coverage limits.

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% for the single `code` parameter (barcode GTIN/EAN, 6-14 digits), so the schema fully documents it. The description only echoes 'by barcode' and adds nothing about format or fallback behavior, which is the expected baseline when the schema does the work.

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+resource with scope: prices of a single product identified by barcode, across every chain that sells it. This implicitly separates it from basket- and city-level siblings (compare_basket_by_chain, cheapest_stores_in_city), but no sibling is named explicitly.

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 'one product (by barcode)' framing signals this is the lookup to use once you already have a barcode (unlike search_products). There is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer routing from the input shape.

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/non-destructive safety, and the description layers on substantial behavioral context: the exact ranking metric (effective_total using shelf or universally-open promotions), the distinction between shelf_total and club_total, coverage/missing reporting, and the free-text-plus-quantity/barcode input model. This is well beyond what annotations alone convey.

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 key scoping and ranking facts are front-loaded in the first sentence, and subsequent sentences each add distinct information (per-branch fields, input syntax, the site-link handoff). It is dense and slightly long, but no sentence is redundant.

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 thoroughly — enumerating effective_total, shelf_total, club_total, coverage, missing, and the try_it_on_site link. Nothing an agent needs to call or interpret this tool appears to be 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 coverage is 100%, so the schema documents both params, but the description still adds real meaning: items are free-text Hebrew names with optional quantities ("במבה x3") or barcodes, and each is matched to a product exposed via items[].matched. The schema's numeric limits (maxLength 80, maxItems 40) are not echoed, so it is not exhaustive.

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 gives a precise verb+resource+scope: pricing an entire shopping list across every supermarket branch of a named city and returning the 5 cheapest. It distinguishes itself from siblings such as cheapest_stores_in_city and compare_basket_by_chain by framing the result set (5 cheapest branches) and the ranking metric (effective_total).

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 states the trigger intent explicitly: "Use this for 'where is my shopping cheapest in <city>'." That is clear context for when to reach for it, but it does not name a sibling alternative or an exclusion (e.g., when to use cheapest_stores_in_city instead).

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, non-destructive and openWorld=false, so the safety profile is covered. The description adds real behavioral content the annotations do not: a hard cap of 20 matches and the exact returned fields (barcode, lowest/median/highest shelf price in ILS across chains, and a link). It does not discuss rate limits, chain coverage, or empty-result 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?

Two sentences, zero filler. The core capability and scope come first, the return payload second, and the routing hint last — a clean front-loaded structure.

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 adequately (fields, price basis in ILS, link, 20-item cap). Annotations cover the safety profile. Minor gaps remain: it never states which chains are covered or what an empty result looks like, so it is strong but not exhaustive.

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 50%: the query parameter is well documented in the schema with a Hebrew example, but limit is not described at all. The description's "up to 20 matches" partially implies the limit ceiling, but it adds nothing about query semantics beyond what the schema already says. Baseline 3 is right when the schema does most of the work and the description only loosely echoes it.

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 products) plus the domain (Israeli supermarket products) and the two accepted lookup keys (Hebrew name or barcode). It also distinguishes itself from the sibling get_product_prices by naming that tool and its role, so an agent can route without opening either 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?

Explicitly routes the agent: use this to find a product, then pass the barcode to get_product_prices for per-chain prices. That is a concrete alternative with a selecting condition, though it gives no explicit "do not use this when" case (e.g. for deals or basket comparisons, which siblings cover).

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 annotations (readOnlyHint, idempotentHint), the description adds real behavioral context: no resource is created at call time, the returned value is a URL plus per-item matching details, and the list is editable/shareable once opened. This confirms and enriches the readOnly annotation rather than contradicting it.

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 core product is front-loaded in the first sentence, with the no-side-effect caveat and return value following. Slightly dense parenthetical, but every clause carries information and nothing is padded.

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 two-parameter, annotation-backed tool with no output schema, the description covers what the tool produces, its side-effect profile, and its return shape (URL plus match results). Only the sibling-differentiation and item-constraint details are 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 only 50% (city has a description, items does not). The description adds meaning to city ('priced in every branch of the city, when given') and hints at per-item matching, but it says nothing about the items constraints (1–40 items, 2–80 chars each), leaving half the parameter surface to 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?

The description states a specific outcome — a link that turns the given items into a WizStore smart shopping list — with concrete attributes (city pricing, editable, shareable). It is clear what the tool produces, but it never names or contrasts with the very similar sibling price_shopping_list, leaving the agent to guess which one to call.

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 only implied: 'Nothing is created until the person opens the link' hints that this is the hand-off-to-human option rather than a direct price computation, but there is no explicit when-to-use statement or reference to alternatives such as price_shopping_list or get_product_prices.

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