albert-heijn-be-mcp

Albert Heijn: Bonus Offers

ah_get_bonus_offers

Read-only

Retrieve Albert Heijn bonus and promotional offers for the current or next week, with optional keyword, category, and previously bought filters to find relevant discounts.

Instructions

Get Albert Heijn bonus/promotional offers. Use this (not ah_search_products) when the user asks what is on bonus/sale/discount. Returns this week's bonus by default; set period='next' for next week's bonus, which AH publishes a few days before the new bonus week starts. Every answer says which week it covers (period, valid_from, valid_until). Supports optional keyword filter to find e.g. cheese on bonus: set query='kaas'. Every offer has a category (AH's bonus category): the answer's categories lists every category of the week with its number of offers (offer_count, before any filter), so set categories to a list of those names to get only those, and food_only=true to leave out the non-food categories (household, drugstore, cooking and table items). Set previously_bought=true for offers on products the user bought before (AH's 'Eerder gekocht'). Group deals (e.g. '2+1 gratis', 'Alle yoghurt 25% korting') have no id but a bonus_segment_id — pass that to ah_get_bonus_group_products to see the individual products in the group. Returns id, bonus_segment_id, title, category, original_price, bonus_price, discount_percentage, bonus_mechanism, and the price fields pack_price, deal_min_quantity, deal_total, deal_price_per_pack, unit_price, unit_price_unit (use these for a shopping line: original_price and bonus_price can be for two packs). When you mention a product or recipe from the result, link its name to its url.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of results to return (default 20)
`query`	No	Optional keyword filter (Dutch or English) applied client-side, e.g. 'kaas', 'vlees', 'bier'
`period`	No	Which bonus week to return: 'current' (default) or 'next'
`food_only`	No	Leave out the non-food categories (default false). With categories, only the food ones of them come back
`categories`	No	Only offers in these bonus categories, by name as in the categories of the answer (case does not matter; an unknown name is an error)
`previously_bought`	No	Only offers on products the user bought before

Output Schema

Name	Required	Description
`offers`	Yes
`period`	Yes	The bonus week this answer is for
`categories`	Yes	Every bonus category of the week with its number of offers, before any filter
`valid_from`	No	First day of the bonus week (YYYY-MM-DD, inclusive); absent when next week is not published yet
`valid_until`	No	Last day of the bonus week (YYYY-MM-DD, inclusive); absent when next week is not published yet

Schema Changelog

Changes observed during successful MCP inspections.

Changed19 schema fields changedv1.2.0Oct 26, 2026

addedInput schema / properties / categories

Added value: +{
+  "description": "Only offers in these bonus categories, by name as in the categories of the answer (case does not matter; an unknown name is an error)",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / food_only

Added value: +{
+  "description": "Leave out the non-food categories (default false). With categories, only the food ones of them come back",
+  "type": "boolean"
+}

addedOutput schema / properties / categories

Added value: +{
+  "description": "Every bonus category of the week with its number of offers, before any filter",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "name": {
+        "type": "string"
+      },
+      "offer_count": {
+        "description": "Offers in this category over the whole week, before any filter",
+        "type": "number"
+      }
+    },
+    "required": [
+      "name",
+      "offer_count"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / offers / items / properties / bonus_price / description

Added value: +"Price of those packs with the deal, as AH sends it (deal_total for deal_min_quantity packs). Absent for deals like '2 voor 1.19'. A group offer has no product of its own: this is AH's example product of the group."

addedOutput schema / properties / offers / items / properties / category

Added value: +{
+  "description": "The ah.be bonus category of the offer, as in the categories of the answer",
+  "type": "string"
+}

addedOutput schema / properties / offers / items / properties / deal_min_quantity

Added value: +{
+  "description": "Packs needed to get the deal (1 for a plain discount); null without a deal, or when the mechanism is not understood",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / offers / items / properties / deal_price_per_pack

Added value: +{
+  "description": "deal_total / deal_min_quantity, in euros",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / offers / items / properties / deal_total

Added value: +{
+  "description": "What you pay for deal_min_quantity packs with the deal, in euros",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / offers / items / properties / original_price / description

Added value: +"Regular price as AH sends it, for the packs the deal needs (deal_min_quantity packs, e.g. two bags for '2e gratis'), not for one pack: pack_price is one pack. A group offer has no product of its own: this is AH's example product of the group."

addedOutput schema / properties / offers / items / properties / pack_price

Added value: +{
+  "description": "Normal shelf price of one pack, in euros",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / offers / items / properties / unit_price

Added value: +{
+  "description": "Normal price per unit_price_unit, where AH gives one",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / offers / items / properties / unit_price_unit

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "kg",
+        "l",
+        "stuk"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The unit of unit_price"
+}

addedOutput schema / properties / offers / items / properties / valid_from

Added value: +{
+  "description": "Only when this offer starts on another day than the week (YYYY-MM-DD)",
+  "type": "string"
+}

addedOutput schema / properties / offers / items / properties / valid_until

Added value: +{
+  "description": "Only when this offer ends on another day than the week (YYYY-MM-DD)",
+  "type": "string"
+}

changedOutput schema / properties / offers / items / required

Previous value: -[
-  "title"
-]New value: +[
+  "title",
+  "pack_price",
+  "deal_min_quantity",
+  "deal_total",
+  "deal_price_per_pack",
+  "unit_price",
+  "unit_price_unit"
+]

addedOutput schema / properties / period

Added value: +{
+  "description": "The bonus week this answer is for",
+  "enum": [
+    "current",
+    "next"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / valid_from

Added value: +{
+  "description": "First day of the bonus week (YYYY-MM-DD, inclusive); absent when next week is not published yet",
+  "type": "string"
+}

addedOutput schema / properties / valid_until

Added value: +{
+  "description": "Last day of the bonus week (YYYY-MM-DD, inclusive); absent when next week is not published yet",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "offers"
-]New value: +[
+  "period",
+  "categories",
+  "offers"
+]

First observedv1.1.0Oct 24, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=true; the description adds substantial behavior beyond that: default week vs next week and AH's publication timing, the guarantee that every answer states period/valid_from/valid_until, the fact that group deals lack an id but carry a bonus_segment_id, and the caveat that original_price/bonus_price may represent two packs. These are operational details an agent could not infer from annotations alone.

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 description is front-loaded with purpose and the sibling exclusion, then moves logically through period, query, categories, food_only, group deals, and return fields. It is dense and runs as one long paragraph, but nearly every sentence carries actionable information for a six-parameter tool with non-obvious price semantics.

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 that an output schema exists and annotations cover the safety profile, the description fills the remaining gaps: week labeling, category counting behavior, group-deal handling, and price-field interpretation for shopping lines. Nothing essential for correct invocation or interpretation appears 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 the baseline is 3, but the description adds useful semantics beyond the schema: why period='next' matters (published a few days early), that categories counts are computed before filtering, and concrete query examples like 'kaas'. It does not fully restate every parameter, which is appropriate given the rich schema.

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 opening sentence names a specific verb and resource ('Get Albert Heijn bonus/promotional offers') and immediately distinguishes the tool from ah_search_products with an explicit 'not ah_search_products' clause. An agent can identify the tool's job and its main confusable sibling 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 Guidelines5/5

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

It states the triggering user intent ('what is on bonus/sale/discount'), the alternative to avoid (ah_search_products), and the correct handoff for group deals (ah_get_bonus_group_products with bonus_segment_id). It also explains when to use period='next', categories, food_only, and previously_bought, leaving little to inference.

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