Yappman Data Supermarket Price Snapshots

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely useful behavioral context beyond that: it discloses coverage limits ('what is not served'), missing/short days in the date range, and the licence/credit obligations an agent must surface when citing.

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?

Front-loaded with the action and the returned contents, followed by a short imperative for when to call it — no wasted sentences. The middle clause is dense and slightly jargon-heavy ('the store setting'), but every listed item corresponds to real returned content.

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?

An output schema exists, so return formatting needn't be described, and the description still enumerates the substantive contents. With zero parameters and full annotation coverage, an agent has everything needed to decide to call it and to interpret what comes back.

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 no parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies a parameterless, single-call metadata fetch.

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?

Names a concrete resource (dataset metadata) and enumerates exactly what it returns: licence/credit, what is not served, store setting, published index weeks, and basket date range with short/missing days. This clearly separates it from the sibling tools, which all retrieve price data rather than dataset-level provenance.

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 closing sentence gives explicit timing guidance: 'Use it before citing or relying on the other tools.' That is a clear usage condition tied to the siblings, though it offers no exclusion or scenario in which calling it is unnecessary.

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 the read-only/idempotent/closed-world profile, and the description adds meaningful context on top: the data is free, CC BY 4.0 licensed, published weekly, excludes product names, and defaults to the latest week when vintage is omitted. It leaves out anything about row volume or pagination, but the presence of an output schema lowers that burden.

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 with what is returned before the negative boundaries and the fallback routing. No filler; each clause either scopes the data or steers the next call.

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 an output schema available and 100% parameter coverage, the description only needs to carry purpose, boundaries, and routing — all present. Licensing and the explicit not-CPI caveat preempt the most likely misuse of shelf-price data.

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 a 3 is the baseline, but the description adds semantics the schema lacks: the default-to-latest behavior of vintage is paired with an explicit discovery path (list_index_vintages) for older weeks, and the output dimensions (retailer, product class) map to the optional filters. The remaining filters (recordType, class) are still left to the schema only.

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 (returns) plus the exact resource and scope: one published week of the free UK/AU online shelf-price index, with the payload enumerated (index levels, week-on-week change, matched-product counts by retailer and product class). An agent can distinguish it from list_index_vintages and lookup_basket_prices from the description alone.

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?

Gives an explicit use case in the user's own words ("how did posted grocery shelf prices move this week"), explicit exclusions (not a CPI, not prices paid, no product names), and an explicit routing rule: omit vintage for the latest week, call list_index_vintages for others. Sibling selection is fully resolved.

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, closed-world and non-destructive, so the description needn't restate safety. It does add genuine context beyond them: result ordering (newest first) and the metadata carried per vintage (publication time, revision, base week). It stops short of noting coverage limits or whether revisions can be retrospective, which would push it to 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?

Three short sentences: what it returns, the sequencing instruction, and the exclusion. The most useful fact — the ordering and fields returned — is front-loaded, 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?

A one-parameter read tool with full annotations and an output schema needs little more. The description covers scope, ordering, sibling relationship and exclusion, leaving return-value detail to the output schema.

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?

Single parameter with 100% schema description coverage and an enum, so the schema fully documents `market`. The description only restates that the index is UK or Australian; it adds no syntax or format detail beyond the schema. Baseline 3 applies.

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 — returning the published weeks (vintages) of the UK/AU shelf-price index — plus the ordering and the fields bundled with each vintage. It is clearly distinguishable from get_shelf_price_index and lookup_basket_prices.

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?

"Use it before get_shelf_price_index to pick a week" gives the sequencing, and "Not for prices" supplies an explicit exclusion pointing at the sibling that does return prices. Nothing is left to inference.

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 extra value here is the snapshot semantics ('static snapshot days, not live'), the coverage ceiling (only 212 products), and the one-row-per-retailer-per-day granularity — all genuinely useful and not present in structured fields. Auth, rate limits, and error behavior are not disclosed, so not 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?

Front-loaded with purpose, then use case, then exclusions in short declarative sentences. The opening sentence is dense with clauses (licence, limits, row shape, field list) but no sentence is redundant, so it stays close to optimal.

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 an output schema present and 100% parameter coverage, the description only needs to supply scope and caveats — and it does: static vintages, 212-product limit, one row per retailer per day, and the Aldi nuance. Nothing an agent needs to invoke or interpret results 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 100%, so the schema already documents date, eans, products and retailers including the Aldi-has-no-barcode caveat. The description adds the cap of 20 barcodes and the either/or semantics of eans vs products, which mostly restates the schema; baseline 3 is correct.

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 (returns posted shelf prices) with the exact resource (UK daily 212-item basket), the input forms (barcodes/EAN or retailer product ids), the shape of the result (up to one row per retailer for one day) and the returned fields. An agent can distinguish it from a name-search or index tool without opening the 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?

Gives an explicit use case in the user's own words ('what did this barcode cost at Tesco, Sainsbury's, Asda or Aldi on a day') and explicit exclusions: not for searching by product name, not live data, only the 212 basket products covered. The boundary conditions that most often cause misselection are all stated.

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