albert-heijn-be-mcp

Albert Heijn: Bonus Group Products

ah_get_bonus_group_products

Read-only

Retrieve individual products in an Albert Heijn bonus promotion group by segment_id to drill into deals like 2+1 gratis kaas; paginate with limit and offset.

Instructions

Get the individual products belonging to a specific Albert Heijn bonus promotion group. Use this to drill into a deal like '2+1 gratis kaas' or 'Alle yoghurt 25% korting'. Get segment_id from the bonus_segment_id field in ah_get_bonus_offers results. Pages of limit products (default 25, at most 100) from offset; total is the size of the whole group. Every product has the group's category. An id that is not in that week's bonus, and period='next' on ah.be, are errors; an empty products list means the group has no products today. Returns the same fields as ah_search_products (image_url only with include_images=true), plus category. 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 products to return (default 25, max 100)
`offset`	No	Number of products to skip, for the next page (default 0)
`period`	No	Bonus week of the offer: 'current' (default); 'next' is an error on ah.be
`segment_id`	Yes	Bonus segment ID from the bonus_segment_id field in ah_get_bonus_offers
`include_images`	No	Include image_url in each product (default false)

Output Schema

Name	Required	Description
`total`	Yes	Products in the group before paging
`period`	Yes	The bonus week this answer is for
`products`	Yes
`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.

Changed20 schema fields changedv1.2.0Oct 26, 2026

addedInput schema / properties / include_images

Added value: +{
+  "description": "Include image_url in each product (default false)",
+  "type": "boolean"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "Maximum number of products to return (default 25, max 100)",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "description": "Number of products to skip, for the next page (default 0)",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

changedInput schema / properties / period / description

Previous value: -"Bonus week of the offer: 'current' (default) or 'next'"New value: +"Bonus week of the offer: 'current' (default); 'next' is an error on ah.be"

addedOutput schema / properties / period

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

addedOutput schema / properties / products / items / properties / bonus_price / description

Added value: +"Price of one pack with the bonus, only where AH sends one: a percentage or euro discount, or a price for one pack ('VOOR 1.99'). Absent for deals on several packs ('2e gratis', '2 voor 5.00'): then deal_min_quantity packs cost deal_total, which is deal_price_per_pack a pack."

addedOutput schema / properties / products / items / properties / category

Added value: +{
+  "description": "The bonus category of the group, as in ah_get_bonus_offers",
+  "type": "string"
+}

addedOutput schema / properties / products / 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 / products / items / properties / deal_price_per_pack

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

addedOutput schema / properties / products / 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 / products / items / properties / image_url / description
```
Added value: +"Only with include_images: true"
```

addedOutput schema / properties / products / items / properties / pack_price

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

addedOutput schema / properties / products / items / properties / price / description

Added value: +"Normal price of one pack in euros, whatever the deal. Same as pack_price."

addedOutput schema / properties / products / items / properties / unit_price

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

addedOutput schema / properties / products / items / properties / unit_price_unit

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

changedOutput schema / properties / products / items / required

Previous value: -[
-  "id",
-  "title",
-  "url",
-  "price",
-  "is_bonus"
-]New value: +[
+  "id",
+  "title",
+  "url",
+  "price",
+  "is_bonus",
+  "pack_price",
+  "deal_min_quantity",
+  "deal_total",
+  "deal_price_per_pack",
+  "unit_price",
+  "unit_price_unit",
+  "category"
+]

addedOutput schema / properties / total

Added value: +{
+  "description": "Products in the group before paging",
+  "type": "number"
+}

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: -[
-  "products"
-]New value: +[
+  "period",
+  "total",
+  "products"
+]

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?

With readOnlyHint already declared, the description still adds substantial behavior: pagination semantics (total is the whole group size, not the page), the meaning of an empty products list, the error conditions, and that image_url only appears with include_images=true. These are runtime traits an agent could not infer from annotations or schema.

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?

Front-loaded with purpose and the id source, and the error/pagination notes are dense but useful. Slightly overstuffed, and the closing instruction mentions 'product or recipe' even though recipes are not returned here, which is minor noise.

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?

Despite an output schema existing, the description usefully characterizes the payload (same fields as ah_search_products plus category) so the agent knows what it is getting. For a 5-parameter, paginated lookup tool, nothing needed to call 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 the baseline is 3, but the description adds meaning beyond it: period='next' is only valid on some domains and errors on ah.be, and limit/offset are framed in terms of the group's total size. It does not extend segment_id or include_images beyond what the schema already says.

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: fetching individual products belonging to a specific Albert Heijn bonus promotion group. It distinguishes itself from ah_get_bonus_offers by framing this as the drill-down step and even gives concrete deal examples ('2+1 gratis kaas').

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?

Explicitly names the upstream sibling and the exact field to take the id from ('segment_id from the bonus_segment_id field in ah_get_bonus_offers results'), which tells the agent when and in what order to call this. It also documents when-not: an id not in that week's bonus and period='next' on ah.be are errors.

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