Skip to main content
Glama

How a kind of product's prices moved

price_movements
Read-onlyIdempotent

How a whole category's prices moved between two dates, in one call: the biggest regular-price rises and falls, promotions starting and ending, member price changes (Tesco Clubcard, SuperValu Real Rewards, Lidl Plus) and pack-size changes, kept apart, with a summary over every product compared (average and median shelf change, counts of rises and falls) overall and per store.

shelf_rise and shelf_fall are changes to the regular price; promotion_started and promotion_ended are changes in what was paid while the regular price stayed the same (a product at 18 euro on promotion and 23 euro after is a promotion ending, not a 27.8% price rise); loyalty_change is a member price moving; pack_change is the same product in a different pack size, confirmed over three days of records (a smaller pack at the same price is a hidden rise); was_price_change is an offer running at both dates while only its "was" price moved, kept out of the shelf figures because nobody paid it. Averages are geometric, so a half-price offer starting and ending cancel out; average_member_paid_change_pct uses member prices where they apply.

Each mover returned costs one credit; the summaries 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": {
      "from_date": "<from_date>"
    },
    "name": "price_movements"
  }
}

Input Schema

NameRequiredDescriptionDefault
groupNoA kind of product: beer, cider, wine, spirits, alcohol, or any product type such as breakfast cereal, butter, coffee, crisps, nappies. Narrower words work too ('vodka', 'red wine').
kindsNoWhich lists to return. Left out: all seven.
limitNoMost products in each list (default 10, at most 50).
queryNoProduct or brand words, with or without group, e.g. 'guinness'.
storeNoOne shop to look in only that one: aldi, tesco, supervalu, dunnes or lidl. Leave it out for all five.
rank_byNoRank each list by the percentage change (pct, the default) or the change in euro (eur).pct
to_dateNoThe later date, YYYY-MM-DD. Left out: today.
categoryNoAn aisle name to narrow by.
from_dateYesThe earlier date, YYYY-MM-DD (prices are kept since May 2026).

Output Schema

NameRequiredDescriptionDefault
noteNo
moversNo
creditsNoWhat this answer cost the person's BasketWatch account and what is left. Missing on a free answer
summaryNoOver EVERY product compared, not only those listed
to_dateNo
from_dateNo
summary_by_storeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed26 schema fields changed
    • addedInput schema / properties / category / description
      Added value: +"An aisle name to narrow by."
    • removedInput schema / properties / category / title
      Removed value: -"Category"
    • addedInput schema / properties / from_date / description
      Added value: +"The earlier date, YYYY-MM-DD (prices are kept since May 2026)."
    • removedInput schema / properties / from_date / title
      Removed value: -"From Date"
    • addedInput schema / properties / group / description
      Added value: +"A kind of product: beer, cider, wine, spirits, alcohol, or any product type such as breakfast cereal, butter, coffee, crisps, nappies. Narrower words work too ('vodka', 'red wine')."
    • removedInput schema / properties / group / title
      Removed value: -"Group"
    • changedInput schema / properties / kinds / anyOf
      Previous value: -[
      -  {
      -    "items": {
      -      "type": "string"
      -    },
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "items": {
      +      "enum": [
      +        "shelf_rise",
      +        "shelf_fall",
      +        "promotion_started",
      +        "promotion_ended",
      +        "loyalty_change",
      +        "pack_change",
      +        "was_price_change"
      +      ],
      +      "type": "string"
      +    },
      +    "type": "array"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / kinds / description
      Added value: +"Which lists to return. Left out: all seven."
    • removedInput schema / properties / kinds / title
      Removed value: -"Kinds"
    • addedInput schema / properties / limit / description
      Added value: +"Most products in each list (default 10, at most 50)."
    • addedInput schema / properties / limit / maximum
      Added value: +50
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • addedInput schema / properties / query / description
      Added value: +"Product or brand words, with or without group, e.g. 'guinness'."
    • removedInput schema / properties / query / title
      Removed value: -"Query"
    • addedInput schema / properties / rank_by / description
      Added value: +"Rank each list by the percentage change (pct, the default) or the change in euro (eur)."
    • addedInput schema / properties / rank_by / enum
      Added value: +[
      +  "pct",
      +  "eur"
      +]
    • removedInput schema / properties / rank_by / title
      Removed value: -"Rank By"
    • 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: +"The later date, YYYY-MM-DD. Left out: today."
    • removedInput schema / properties / to_date / title
      Removed value: -"To Date"
    • removedInput schema / title
      Removed value: -"price_movementsArguments"
    • 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. Changed1 schema field changed
    • changedOutput schema / $defs / Mover / properties / kind / description
      Previous value: -"shelf_rise, shelf_fall, promotion_started, promotion_ended, loyalty_change or pack_change"New value: +"shelf_rise, shelf_fall, promotion_started, promotion_ended, loyalty_change, pack_change or was_price_change"
  3. Changed1 schema field changed
    • changedOutput schema / $defs / PriceOnDate / 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"
  4. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations cover safety (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: per-mover credit cost with free summaries, geometric averaging so offer start/end cancel out, and three-day confirmation for pack changes. It also discloses non-obvious classification rules (a promotion ending is not a price rise; was_price_change is excluded from shelf figures), which prevents misreading results.

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?

Well front-loaded: the first sentence states the whole job and the returned structure, then paragraphs drill into mover semantics and cost. The prose is dense with long clauses and parenthetical examples, which slows scanning, but almost nothing is filler given the classification complexity.

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?

For a 9-parameter, seven-category analytical tool with an output schema and full schema coverage, this is complete: mover semantics, ranking behavior, date bounds, store coverage, and cost model are all addressed. The remaining parameters (group, query, limit, rank_by, store) are documented in the schema, so nothing essential is missing.

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 baseline is 3, but the description goes further by explaining the real-world meaning of each `kinds` enum value and the distinction between them, which the schema only lists as bare strings. It adds a semantic model (regular price vs paid price vs member price) rather than restating parameter types.

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?

Names a specific verb and resource plus scope ('How a whole category's prices moved between two dates, in one call') and enumerates the exact seven mover types returned. It is clearly distinguishable from a plain history or comparison tool, since it is about ranked movers plus an aggregate summary.

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

Usage Guidelines3/5

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

The description gives strong implicit guidance by defining what each mover type means, which dictates which `kinds` to request, and the 'in one call' phrasing hints at the alternative of multiple queries. However, it never names a sibling (recent_price_changes, get_price_history, compare_prices) or states when another tool is the better choice.

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