BasketWatch

Everything on offer at one shop

get_promotions

Read-onlyIdempotent

List products currently on promotion at a given supermarket, the biggest saving the shop states first. Every promotion can be reached: each call returns one page, and offset moves through the whole list. These are the shop's own offers, as it states them, on the products it still lists. Aldi runs no multibuys or member prices: its list is the price cuts and offers its own site shows.

Returns offer label (e.g. "3 for €5", "SAVE €0.75"), was-price, validity window, offer_ends (the last day the offer applies, Irish time), and where applicable Tesco Clubcard prices, SuperValu Real Rewards prices, Dunnes member offers or Lidl Plus prices (scan the Lidl Plus app at the till). next_offset is the next page's offset, and is missing on the last page. Each offer returned costs one credit.

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": {
      "store": "<store>"
    },
    "name": "get_promotions"
  }
}

Input Schema

Name	Required	Description
`limit`	No	How many offers to return in one page (default 25, at most 200).
`store`	Yes	The shop: aldi, tesco, supervalu, dunnes or lidl.
`offset`	No	How many rows to skip, for the next page: the next_offset of the page before (default 0).

Output Schema

Name	Required	Description
`hint`	No	What to try, when the page is empty
`as_of`	No	The day these offers were recorded, YYYY-MM-DD
`store`	No
`offset`	No	How many rows this page skipped
`credits`	No	What this answer cost the person's BasketWatch account and what is left. Missing on a free answer
`promotions`	No	One page, the biggest saving the shop states first
`next_offset`	No	The offset of the next page; missing on the last

Schema Changelog

Changes observed during successful MCP inspections.

Changed32 schema fields changedNov 11, 2026

addedInput schema / properties / limit / description

Added value: +"How many offers to return in one page (default 25, at most 200)."

addedInput schema / properties / limit / maximum
```
Added value: +200
```
addedInput schema / properties / limit / minimum
```
Added value: +1
```
removedInput schema / properties / limit / title
```
Removed value: -"Limit"
```

addedInput schema / properties / offset / description

Added value: +"How many rows to skip, for the next page: the next_offset of the page before (default 0)."

addedInput schema / properties / offset / minimum
```
Added value: +0
```
removedInput schema / properties / offset / title
```
Removed value: -"Offset"
```

addedInput schema / properties / store / description

Added value: +"The shop: aldi, tesco, supervalu, dunnes or lidl."

addedInput schema / properties / store / enum

Added value: +[
+  "aldi",
+  "tesco",
+  "supervalu",
+  "dunnes",
+  "lidl"
+]

removedInput schema / properties / store / title
```
Removed value: -"Store"
```

removedInput schema / title

Removed value: -"get_promotionsArguments"

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 / Promotion / properties / brand

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Brand"
+}

addedOutput schema / $defs / Promotion / properties / clubcard_price

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Member price where one applies: Tesco Clubcard, SuperValu Real Rewards or Lidl Plus",
+  "title": "Clubcard Price"
+}

addedOutput schema / $defs / Promotion / properties / id / description

Added value: +"The shop's own product id, e.g. tesco:12345 (an Aldi id has no shop in front): the form a product_ids parameter takes"

addedOutput schema / $defs / Promotion / properties / pack_size

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Pack Size"
+}

addedOutput schema / $defs / Promotion / 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 / Promotion / 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 / Promotion / properties / store

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Store"
+}

addedOutput schema / $defs / Promotion / properties / unit_basis

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The measure unit_price is in, as the shop states it: '1 KG', '100g', '75cl', 'each'",
+  "title": "Unit Basis"
+}

addedOutput schema / $defs / Promotion / properties / unit_price

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "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",
+  "title": "Unit Price"
+}

addedOutput schema / additionalProperties
```
Added value: +true
```

addedOutput schema / properties / as_of

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The day these offers were recorded, YYYY-MM-DD",
+  "title": "As Of"
+}

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"
+}

addedOutput schema / properties / hint

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "What to try, when the page is empty",
+  "title": "Hint"
+}

addedOutput schema / properties / next_offset

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The offset of the next page; missing on the last",
+  "title": "Next Offset"
+}

addedOutput schema / properties / offset

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "How many rows this page skipped",
+  "title": "Offset"
+}

addedOutput schema / properties / promotions

Added value: +{
+  "description": "One page, the biggest saving the shop states first",
+  "items": {
+    "$ref": "#/$defs/Promotion"
+  },
+  "title": "Promotions",
+  "type": "array"
+}

removedOutput schema / properties / result

Removed value: -{
-  "items": {
-    "$ref": "#/$defs/Promotion"
-  },
-  "title": "Result",
-  "type": "array"
-}

addedOutput schema / properties / store

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Store"
+}

removedOutput schema / required
```
Removed value: -[
-  "result"
-]
```

changedOutput schema / title

Previous value: -"get_promotionsOutput"New value: +"PromotionList"

Changed1 schema field changedNov 2, 2026

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "title": "Offset",
+  "type": "integer"
+}

Changed1 schema field changedOct 27, 2026

addedOutput schema / $defs / Promotion / 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"
+}

First observedOct 12, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Adds substantial context beyond the annotations: one page per call, offset paging, next_offset absent on the last page, per-offer credit cost, Irish-time offer_ends, and store-specific loyalty pricing behavior. Since readOnly/idempotent are already declared, this is strong supplementary disclosure, though it omits what happens on invalid store/offset or when paging past the end.

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?

Purpose and paging are front-loaded, and most sentences carry real information (pricing, credits, last-page marker). The loyalty-scheme sentence is long and partly redundant with the output schema, and the Aldi sentence is narrow, keeping it short of a 5.

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?

The definition covers pagination, cost, sorting, and store quirks, which is more than enough for a three-parameter read tool that also has an output schema. Minor gaps remain around error behavior and whether promotions are filtered by date, but nothing an agent needs to invoke it correctly 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 framing offset as page traversal and tying it to next_offset, and by explaining the ordering of results. Store semantics are enriched with the Aldi behavior note that the enum alone does not convey.

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?

States a specific verb and resource ('list products currently on promotion') and pins the scope to a single supermarket, which separates it from cross-store tools like compare_price_across_stores or best_deals. It also discloses the ordering rule (biggest stated saving first), so an agent knows what it gets 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.

Usage Guidelines3/5

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

Usage is implied rather than prescribed: the description makes clear this is the per-shop promotion listing and notes the Aldi caveat (no multibuys or member prices), but it never says when to prefer a sibling or when this tool is the wrong choice. There are no explicit exclusions or alternatives named.

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

All BasketWatch tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?