Skip to main content
Glama

Price a shopping list or receipt

price_basket
Read-onlyIdempotent

Price a whole shopping list, or every line of a grocery receipt (up to 100 lines in one call), at Aldi, Tesco, SuperValu, Dunnes Stores and Lidl: each item matched to the same product at every store, the cheapest store for each item, each store's basket total, and a cheaper product of the same kind (often own-label) where one exists.

Each line takes name (plain words with brand and size, e.g. "avonmore fresh milk 2l"; receipt abbreviations such as "AVNMR FRSH MLK 2L" match poorly) and optionally sku (the retailer's item number as printed on its receipts; the name is used when the number is not found), barcode, store, quantity, and paid (the line total, which gives the saving against what was paid). Irish product names say "low fat milk" for what the UK calls "semi skimmed". Bags, deposits, discounts and totals are not products.

Returns, per line, the match and matched_by (sku, barcode or name), the cheapest store and price, a cheaper alternative with its pack size and, for a receipt, price_at_store_bought; then each store's total with its items_missing, cheapest_complete_store, mix_and_match_total and not_found. A store's total covers only the lines found in its online range, so a total with items_missing is a smaller basket, not a cheaper shop. Prices are each retailer's online shelf price from the overnight collection; in-store prices can differ. Member prices (Tesco Clubcard, SuperValu Real Rewards, Lidl Plus) are reported separately. Each matched item costs one credit; items not found are free.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "items": "<items>"
    },
    "name": "price_basket"
  }
}

Input Schema

NameRequiredDescriptionDefault
itemsYesThe lines, up to 100, e.g. [{'name': 'avonmore fresh milk 2l', 'quantity': 2}, {'name': 'brennans wholemeal bread'}]; for a receipt add sku and paid: {'sku': '100685955', 'name': 'dunnes baked beans', 'quantity': 2, 'paid': 1.30}.
storeNoThe shop the receipt is from (aldi, tesco, supervalu, dunnes or lidl), used for any line that names none. Leave it out for a shopping list.

Output Schema

NameRequiredDescriptionDefault
noteNo
as_ofNoPrice date, YYYY-MM-DD
itemsNo
creditsNoWhat this answer cost the person's BasketWatch account and what is left. Missing on a free answer
not_foundNoItems with no match
paid_totalNo
different_packNoItems priced at another pack size than the one asked for, so not like for like
saving_vs_paidNo
lidl_plus_totalNoLidl total using Lidl Plus prices where Lidl has one
totals_by_storeNo
mix_and_match_totalNoEach item bought at its cheapest store
tesco_clubcard_totalNoTesco total using Clubcard prices where Tesco has one
cheapest_complete_storeNoThe cheapest store among those with every matched item found in its online range today
with_alternatives_totalNoAs mix_and_match_total, taking each cheaper alternative where there is one
supervalu_real_rewards_totalNoSuperValu total using Real Rewards prices where SuperValu has one

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed26 schema fields changed
    • removedInput schema / $defs / BasketItem / properties / barcode / title
      Removed value: -"Barcode"
    • removedInput schema / $defs / BasketItem / properties / count / title
      Removed value: -"Count"
    • removedInput schema / $defs / BasketItem / properties / name / title
      Removed value: -"Name"
    • removedInput schema / $defs / BasketItem / properties / paid / title
      Removed value: -"Paid"
    • removedInput schema / $defs / BasketItem / properties / quantity / title
      Removed value: -"Quantity"
    • removedInput schema / $defs / BasketItem / properties / size / title
      Removed value: -"Size"
    • removedInput schema / $defs / BasketItem / properties / sku / title
      Removed value: -"Sku"
    • removedInput schema / $defs / BasketItem / properties / store / title
      Removed value: -"Store"
    • removedInput schema / $defs / BasketItem / title
      Removed value: -"BasketItem"
    • addedInput schema / properties / items / description
      Added value: +"The lines, up to 100, e.g. [{'name': 'avonmore fresh milk 2l', 'quantity': 2}, {'name': 'brennans wholemeal bread'}]; for a receipt add sku and paid: {'sku': '100685955', 'name': 'dunnes baked beans', 'quantity': 2, 'paid': 1.30}."
    • removedInput schema / properties / items / title
      Removed value: -"Items"
    • changedInput schema / properties / store / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "aldi",
      +      "tesco",
      +      "supervalu",
      +      "dunnes",
      +      "lidl"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / store / description
      Added value: +"The shop the receipt is from (aldi, tesco, supervalu, dunnes or lidl), used for any line that names none. Leave it out for a shopping list."
    • removedInput schema / properties / store / title
      Removed value: -"Store"
    • removedInput schema / title
      Removed value: -"price_basketArguments"
    • addedOutput schema / $defs / BasketAlternative / properties / price_per_kg
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "unit_price worked out per kilo, where the shop prices the product by weight: the figure to compare packs of different sizes on (per kilo drained, where unit_basis says drained weight)",
      +  "title": "Price Per Kg"
      +}
    • addedOutput schema / $defs / BasketAlternative / properties / price_per_litre
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "unit_price worked out per litre, where the shop prices the product by volume",
      +  "title": "Price Per Litre"
      +}
    • addedOutput schema / $defs / BasketAlternative / properties / unit_basis / description
      Added value: +"The measure unit_price is in, as the shop states it: '1 KG', '100g', '75cl', 'each'"
    • addedOutput schema / $defs / BasketAlternative / properties / unit_price / description
      Added value: +"The shop's own unit price, in the measure unit_basis names: per kg at one shop, per 100g or per 75cl at another, so as it stands it does not compare across rows"
    • changedOutput schema / $defs / BasketLine / properties / pack_differs / description
      Previous value: -"True when this was priced at another pack size or count than the one the line asked for: say so, and never add it to a total as like for like"New value: +"True when this was priced at another pack size or count than the one the line asked for: not like for like, in the line or in a total"
    • addedOutput schema / $defs / BasketStorePrice / properties / price_per_kg
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "unit_price worked out per kilo, where the shop prices the product by weight: the figure to compare packs of different sizes on (per kilo drained, where unit_basis says drained weight)",
      +  "title": "Price Per Kg"
      +}
    • addedOutput schema / $defs / BasketStorePrice / properties / price_per_litre
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "unit_price worked out per litre, where the shop prices the product by volume",
      +  "title": "Price Per Litre"
      +}
    • addedOutput schema / $defs / BasketStorePrice / properties / unit_basis / description
      Added value: +"The measure unit_price is in, as the shop states it: '1 KG', '100g', '75cl', 'each'"
    • addedOutput schema / $defs / BasketStorePrice / properties / unit_price / description
      Added value: +"The shop's own unit price, in the measure unit_basis names: per kg at one shop, per 100g or per 75cl at another, so as it stands it does not compare across rows"
    • addedOutput schema / $defs / Credits
      Added value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "left": {
      +      "anyOf": [
      +        {
      +          "type": "integer"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "description": "Credits left on the account after it",
      +      "title": "Left"
      +    },
      +    "note": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "description": "Said when the balance is low, or when it cut this answer short",
      +      "title": "Note"
      +    },
      +    "used": {
      +      "description": "Credits this answer cost: one for each record it returned",
      +      "title": "Used",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "used"
      +  ],
      +  "title": "Credits",
      +  "type": "object"
      +}
    • addedOutput schema / properties / credits
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/Credits"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "What this answer cost the person's BasketWatch account and what is left. Missing on a free answer"
      +}
  2. Changed5 schema fields changed
    • addedInput schema / $defs / BasketItem / properties / count
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "How many items in the pack, when not in name, e.g. 12 for a dozen eggs, 6 for a six pack. Not how many packs were bought: that is quantity",
      +  "title": "Count"
      +}
    • changedInput schema / $defs / BasketItem / properties / name / description
      Previous value: -"Brand, product and size in plain words, e.g. 'avonmore fresh milk 2l'"New value: +"Brand, product and size in plain words, e.g. 'avonmore fresh milk 2l', '12 eggs', 'dozen eggs'"
    • addedInput schema / $defs / BasketItem / properties / size
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The pack size wanted, when not in name, e.g. '2L', '500g': chooses that size at each store",
      +  "title": "Size"
      +}
    • addedOutput schema / $defs / BasketLine / properties / asked
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The size or count the line asked for, read from its name or its size and count: {'size': '2 L'}, {'count': 12}, {'count': 6, 'each': '330 ml'}",
      +  "title": "Asked"
      +}
    • changedOutput schema / $defs / BasketLine / properties / pack_differs / description
      Previous value: -"True when this was priced at another pack size than the one the line asked for"New value: +"True when this was priced at another pack size or count than the one the line asked for: say so, and never add it to a total as like for like"
  3. Changed2 schema fields changed
    • addedOutput schema / $defs / BasketLine / properties / pack_differs
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "True when this was priced at another pack size than the one the line asked for",
      +  "title": "Pack Differs"
      +}
    • addedOutput schema / properties / different_pack
      Added value: +{
      +  "description": "Items priced at another pack size than the one asked for, so not like for like",
      +  "items": {
      +    "type": "string"
      +  },
      +  "title": "Different Pack",
      +  "type": "array"
      +}
  4. Changed3 schema fields changed
    • changedOutput schema / $defs / BasketMatch / properties / prices / description
      Previous value: -"Keyed by store; a store missing here does not stock this product"New value: +"Keyed by store; a store missing here did not have this product in its online range today (it may still sell it in store)"
    • changedOutput schema / $defs / StoreTotal / properties / items_missing / description
      Previous value: -"Matched items this store does not stock"New value: +"Matched items not found in this store's online range today (it may still sell them in store)"
    • changedOutput schema / properties / cheapest_complete_store / description
      Previous value: -"The cheapest store among those stocking every matched item"New value: +"The cheapest store among those with every matched item found in its online range today"
  5. Changed1 schema field changed
    • addedOutput schema / $defs / BasketStorePrice / properties / offer_ends
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Last day the offer applies, YYYY-MM-DD, Irish time, where the retailer states it",
      +  "title": "Offer Ends"
      +}
  6. Changed2 schema fields changed
    • changedOutput schema / $defs / BasketStorePrice / properties / clubcard_price / description
      Previous value: -"Tesco Clubcard price, Tesco only"New value: +"Member price where one applies: Tesco Clubcard, SuperValu Real Rewards or Lidl Plus"
    • addedOutput schema / properties / supervalu_real_rewards_total
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "SuperValu total using Real Rewards prices where SuperValu has one",
      +  "title": "Supervalu Real Rewards Total"
      +}
  7. Changed2 schema fields changed
    • changedInput schema / $defs / BasketItem / properties / store / description
      Previous value: -"aldi, tesco, supervalu or dunnes; defaults to the basket's store"New value: +"aldi, tesco, supervalu, dunnes or lidl; defaults to the basket's store"
    • addedOutput schema / properties / lidl_plus_total
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Lidl total using Lidl Plus prices where Lidl has one",
      +  "title": "Lidl Plus Total"
      +}
  8. First observed

TDQS

A4.5/5.0
Behavior4/5

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

With readOnlyHint and idempotentHint already supplied, the description still adds real operational context: one credit per matched item with unmatched items free, prices sourced from an overnight online shelf-price collection that may differ in store, and member prices reported separately. It also flags the important interpretation caveat that a store total with items_missing represents a smaller basket rather than a cheaper shop. The only minor omission is nothing about latency or limits beyond the 100-line cap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The structure is front-loaded: purpose and outputs first, then per-line input guidance, then return shape and pricing caveats. It is dense with long sentences and some detail (the localisation note, member-price aside) that could be tightened, but nearly every sentence carries information an agent would otherwise get wrong.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a rich schema and an output schema, the description covers what structured fields cannot: credit cost, data freshness, store-coverage caveats on totals, and matching behaviour. An agent has enough to construct correct calls for both list and receipt modes and to interpret the returned totals sensibly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description goes well beyond it by prescribing name formatting ('plain words with brand and size'), warning that receipt abbreviations like 'AVNMR FRSH MLK 2L' match poorly, explaining the fallback from sku to name, and noting Irish versus UK naming ('low fat milk' vs 'semi skimmed'). It also clarifies that paid enables a saving calculation, which the schema only describes as a line total.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 ('Price a whole shopping list, or every line of a grocery receipt') and names the exact outputs returned (per-item cheapest store, per-store basket totals, cheaper alternatives). That bulk-basket scope distinguishes it from per-product siblings such as compare_price_across_stores and get_product_details without needing their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly splits the two modes: shopping list versus receipt, with 'for a receipt add sku and paid' and 'Leave it out for a shopping list', and caps usage at 100 lines. It also warns that receipt abbreviations match poorly and that bags, deposits, discounts and totals are not products, which is concrete when-to-use guidance. It stops short of naming alternatives or stating explicit exclusions relative to sibling tools.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources