Skip to main content
Glama

Price history

get_price_history
Read-onlyIdempotent

A product's recorded daily prices over a date range. BasketWatch has kept every night's price at Aldi, Tesco, SuperValu and Dunnes Stores since May 2026 and at Lidl since 17 October 2026, and, with with_nutrition_and_ingredients, each day's nutrition per 100g or 100ml and ingredients list as the retailer's own data stated them, kept since 16 October 2026: for questions like "has the sugar in Frosties changed".

Takes product ids (as returned in product results; an Aldi id has no store prefix, and "aldi:" in front of one is accepted) or a query; with a query, the closest matching product at each shop is looked up first, one a shop, so a month of days fits whole, and each row names the product it is for. A range returns one row per product per day, and each row costs one credit; with from_date equal to to_date, one day's price is returned. One credit per row comes to about 31 for one product for a month and about 155 for a product at five shops, and a look-up by name adds one for each shop that has the product.

Every product gets the same days. When products x days would pass the row limit, the range is shortened to its most recent days for all of them and note says so; ids with no price in the range are listed in not_found.

Returns rows (id, name, store, scrape_date, price, unit_price, unit_basis, clubcard_price, offer_text, was_price), the days covered, not_found, note.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_price_history"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMost rows to return in all (default and most 200). Fewer than products x days cuts the range to its most recent days for every product.
queryNoProduct name words, used when no product_ids are given: the closest match at each shop is looked up, one a shop.
storeNoOne shop to look in only that one: aldi, tesco, supervalu, dunnes or lidl. Leave it out for all five.
to_dateNoLast day, YYYY-MM-DD. Left out: today.
from_dateNoFirst day, YYYY-MM-DD. Left out: 30 days before to_date.
product_idsNoProduct ids exactly as another tool gave them, e.g. ['tesco:300793546', 'dunnes:100873410', '000000000000387044'], up to 50. The sure way to name a product.
with_nutrition_and_ingredientsNoTrue to add each day's nutrition per 100g or 100ml to every row, and the ingredients list on a product's first day and on any day it changed. Days before 16 October 2026 have none.

Output Schema

NameRequiredDescriptionDefault
noteNoWhat was left out and why, when anything was
rowsNoOne row per product per day recorded, each product's days in order
creditsNoWhat this answer cost the person's BasketWatch account and what is left. Missing on a free answer
to_dateNoLast day covered, YYYY-MM-DD
productsNoHow many products have rows
from_dateNoFirst day covered, YYYY-MM-DD
not_foundNoRequested ids with no price recorded in the range: an unknown id, or a product not on sale then

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed21 schema fields changed
    • addedInput schema / properties / from_date / description
      Added value: +"First day, YYYY-MM-DD. Left out: 30 days before to_date."
    • removedInput schema / properties / from_date / title
      Removed value: -"From Date"
    • changedInput schema / properties / limit / anyOf
      Previous value: -[
      -  {
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "maximum": 200,
      +    "minimum": 1,
      +    "type": "integer"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / limit / description
      Added value: +"Most rows to return in all (default and most 200). Fewer than products x days cuts the range to its most recent days for every product."
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • addedInput schema / properties / product_ids / description
      Added value: +"Product ids exactly as another tool gave them, e.g. ['tesco:300793546', 'dunnes:100873410', '000000000000387044'], up to 50. The sure way to name a product."
    • removedInput schema / properties / product_ids / title
      Removed value: -"Product Ids"
    • addedInput schema / properties / query / description
      Added value: +"Product name words, used when no product_ids are given: the closest match at each shop is looked up, one a shop."
    • removedInput schema / properties / query / title
      Removed value: -"Query"
    • 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: +"One shop to look in only that one: aldi, tesco, supervalu, dunnes or lidl. Leave it out for all five."
    • removedInput schema / properties / store / title
      Removed value: -"Store"
    • addedInput schema / properties / to_date / description
      Added value: +"Last day, YYYY-MM-DD. Left out: today."
    • removedInput schema / properties / to_date / title
      Removed value: -"To Date"
    • addedInput schema / properties / with_nutrition_and_ingredients / description
      Added value: +"True to add each day's nutrition per 100g or 100ml to every row, and the ingredients list on a product's first day and on any day it changed. Days before 16 October 2026 have none."
    • removedInput schema / properties / with_nutrition_and_ingredients / title
      Removed value: -"With Nutrition And Ingredients"
    • removedInput schema / title
      Removed value: -"get_price_historyArguments"
    • 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 / $defs / PricePoint / 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 / PricePoint / 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 / 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. Changed1 schema field changed
    • changedOutput schema / $defs / PricePoint / properties / clubcard_price / description
      Previous value: -"Tesco Clubcard price that day"New value: +"Member price that day: Tesco Clubcard, SuperValu Real Rewards or Lidl Plus"
  3. Changed4 schema fields changed
    • addedInput schema / properties / with_nutrition_and_ingredients
      Added value: +{
      +  "default": false,
      +  "title": "With Nutrition And Ingredients",
      +  "type": "boolean"
      +}
    • addedOutput schema / $defs / Nutrition
      Added value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "carbohydrate_g": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Carbohydrate G"
      +    },
      +    "energy_kcal": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Energy Kcal"
      +    },
      +    "energy_kj": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Energy Kj"
      +    },
      +    "fat_g": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Fat G"
      +    },
      +    "protein_g": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Protein G"
      +    },
      +    "salt_g": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Salt G"
      +    },
      +    "sugars_g": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Sugars G"
      +    }
      +  },
      +  "title": "Nutrition",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / PricePoint / properties / ingredients
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The ingredients list, on a product's first day and on any day it changed (with_nutrition_and_ingredients)",
      +  "title": "Ingredients"
      +}
    • addedOutput schema / $defs / PricePoint / properties / nutrition_per_100
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/Nutrition"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "That day's nutrition per 100g or 100ml, as the retailer's own data stated it (with_nutrition_and_ingredients)"
      +}
  4. Changed13 schema fields changed
    • addedInput schema / properties / limit / anyOf
      Added value: +[
      +  {
      +    "type": "integer"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / limit / default
      Previous value: -60New value: +null
    • removedInput schema / properties / limit / type
      Removed value: -"integer"
    • addedOutput schema / additionalProperties
      Added value: +true
    • addedOutput schema / properties / from_date
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "First day covered, YYYY-MM-DD",
      +  "title": "From Date"
      +}
    • addedOutput schema / properties / not_found
      Added value: +{
      +  "description": "Requested ids with no price recorded in the range: an unknown id, or a product not on sale then",
      +  "items": {
      +    "type": "string"
      +  },
      +  "title": "Not Found",
      +  "type": "array"
      +}
    • addedOutput schema / properties / note
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "What was left out and why, when anything was",
      +  "title": "Note"
      +}
    • addedOutput schema / properties / products
      Added value: +{
      +  "default": 0,
      +  "description": "How many products have rows",
      +  "title": "Products",
      +  "type": "integer"
      +}
    • removedOutput schema / properties / result
      Removed value: -{
      -  "items": {
      -    "$ref": "#/$defs/PricePoint"
      -  },
      -  "title": "Result",
      -  "type": "array"
      -}
    • addedOutput schema / properties / rows
      Added value: +{
      +  "description": "One row per product per day recorded, each product's days in order",
      +  "items": {
      +    "$ref": "#/$defs/PricePoint"
      +  },
      +  "title": "Rows",
      +  "type": "array"
      +}
    • addedOutput schema / properties / to_date
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Last day covered, YYYY-MM-DD",
      +  "title": "To Date"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "result"
      -]
    • changedOutput schema / title
      Previous value: -"get_price_historyOutput"New value: +"PriceHistory"
  5. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already declare a safe, idempotent, read-only, open-world call, and the description adds substantial context beyond that: per-row credit costs (about 31 for a month, about 155 across five shops, plus lookup cost per shop), data vintage per retailer, nutrition/ingredients availability since 16 October 2026, and how truncation and not_found are reported.

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

Conciseness3/5

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

Front-loads purpose well, but the credit explanation is stated twice (per-row cost, then again as 'one credit per row comes to about 31'), the row-field list is redundant against the output schema, and there is a duplicated word ('with with_nutrition_and_ingredients'). Dense but not tight.

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

Completeness4/5

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

For a seven-parameter tool with credit costs and range-truncation behavior, the description covers the important failure modes (not_found, note when the range is shortened) and the coverage-date caveats. Listing every returned row field is unnecessary given an output schema exists.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: Aldi ids may appear with or without the 'aldi:' prefix, a query resolves the closest match once per shop, and nutrition data is absent before 16 October 2026. That goes beyond what the parameter descriptions alone say.

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

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: recorded daily prices for a product over a date range, with per-retailer coverage dates. That clearly separates it from product-detail or promotion lookups, though it never names a sibling tool to route away from.

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?

Gives concrete use conditions: name a product by ids (the sure way) or by query, one day's price when from_date equals to_date, and the range gets trimmed when the row limit would be exceeded. It stops short of explicitly saying when to prefer this over price_movements or compare_price_across_stores.

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