ah-mcp

Albert Heijn: Bonus Group Products

ah_get_bonus_group_products

Read-only

Get all individual products in an Albert Heijn bonus promotion group by segment ID, so you can expand deals like '2+1 gratis kaas' and check current or next week.

Instructions

Get all 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. For an offer from next week's bonus, set period='next'. Returns the same fields as ah_search_products. When you mention a product or recipe from the result, link its name to its url.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`period`	No	Bonus week of the offer: 'current' (default) or 'next'
`segment_id`	Yes	Bonus segment ID from the bonus_segment_id field in ah_get_bonus_offers

Output Schema

TableJSON Schema

Name	Required	Description	Default
`products`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.3.1Oct 5, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "products": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "bonus_mechanism": {
+            "type": "string"
+          },
+          "bonus_price": {
+            "type": "number"
+          },
+          "id": {
+            "type": "number"
+          },
+          "image_url": {
+            "type": "string"
+          },
+          "is_bonus": {
+            "type": "boolean"
+          },
+          "price": {
+            "type": "number"
+          },
+          "title": {
+            "type": "string"
+          },
+          "unit": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "url",
+          "price",
+          "is_bonus"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "products"
+  ],
+  "type": "object"
+}

First observedv1.0.0Oct 5, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it says the payload matches ah_search_products fields and instructs the agent to link a returned product/recipe name to its url when mentioning it. A slight gap remains in that return shape is deferred to another tool rather than described, but with an output schema present this is minor.

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?

Five short sentences, front-loaded with the core purpose, then the workflow linkage, then the output convention. Each sentence carries distinct information, though the trailing url-linking instruction is a formatting convention rather than tool mechanics and could be trimmed.

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 two-parameter read tool with an output schema and readOnlyHint annotation, the description covers purpose, parameter sourcing, the next-week edge case, and return-field expectations. An agent has everything needed to call it correctly on the first attempt.

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

Parameters3/5

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

Schema description coverage is 100% and the schema already documents both parameters, including the enum values for period and the origin of segment_id. The description's parameter notes ('set period=next for next week's bonus', 'get segment_id from bonus_segment_id') largely restate the schema, so the baseline of 3 applies.

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 description states a specific verb (Get) and resource (individual products in a bonus promotion group), and immediately contrasts it with the aggregate view by telling the agent it is for drilling into a deal like '2+1 gratis kaas'. This clearly distinguishes it from ah_get_bonus_offers and ah_search_products without opening either 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 gives explicit when-to-use guidance ('drill into a deal'), tells the agent exactly where the required segment_id comes from (the bonus_segment_id field of ah_get_bonus_offers results), and covers the edge case of next week's promotion with period='next'. Nothing about tool selection is left to inference.

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