albert-heijn-be-mcp

Albert Heijn: Search Products

ah_search_products

Read-only

Search Albert Heijn products by keyword, run multiple queries in one call, and filter by diet, allergens, or promotions to find matching groceries.

Instructions

Search Albert Heijn (Dutch supermarket) products by keyword. Pass one or more queries (max 10) to search for several products in one call. Prefer Dutch search terms for best results: e.g. 'melk' (milk), 'kaas' (cheese), 'brood' (bread), 'kip' (chicken), 'appel' (apple). Set bonus=true to return only products currently on promotion; this also finds product promotions, such as volume discounts ('5% volume voordeel' on a 2-pack), that ah_get_bonus_offers does not list. filters narrows results to products matching all of them, e.g. ['organic', 'gluten_free']: organic, prijsfavoriet (AH's budget label), new, frozen, a diet (vegan, vegetarian, low_sugar, low_fat, low_salt), or free from an allergen (gluten_free, lactose_free, milk_free, egg_free, nut_free, peanut_free, soy_free, fish_free, shellfish_free, sesame_free, celery_free, mustard_free, lupin_free, sulphite_free). sort orders results: relevance (default), price_low_high, price_high_low, most_bought (by this user), nutriscore. Returns, per query: id, title, price, bonus_price, unit, is_bonus, bonus_mechanism, and the price fields pack_price, deal_min_quantity, deal_total, deal_price_per_pack, unit_price, unit_price_unit (image_url only with include_images=true). When you mention a product or recipe from the result, link its name to its url.

Input Schema

Name	Required	Description
`sort`	No	Result order (default relevance)
`bonus`	No	Return only products currently on bonus/promotion
`limit`	No	Maximum results per query (default 10 for one query, 5 for several; max 30)
`filters`	No	Only products matching all of these, e.g. ["organic", "vegan"]
`queries`	Yes	Search queries in Dutch or English, e.g. ["melk"] or ["melk", "kaas", "brood"] (max 10)
`include_images`	No	Include image_url in each result (default false)

Output Schema

Name	Required	Description	Default
`searches`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv1.2.0Oct 26, 2026

addedInput schema / properties / include_images

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

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

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

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

addedOutput schema / properties / searches / items / properties / results / items / properties / pack_price

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

addedOutput schema / properties / searches / items / properties / results / items / properties / price / description
```
Added value: +"Normal price of one pack in euros, whatever the deal. Same as pack_price."
```

addedOutput schema / properties / searches / items / properties / results / items / properties / unit_price

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

addedOutput schema / properties / searches / items / properties / results / 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 / searches / items / properties / results / 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"
+]

First observedv1.1.0Oct 24, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations only cover readOnlyHint=true, so the description carries the rest and does so well: it discloses the 10-query cap, default limits, that bonus=true changes result semantics, that image_url only appears with include_images=true, and enumerates the returned fields. Missing items like rate limits, auth requirements, or what happens with no-match queries keep it from a 5.

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 Dutch-term guidance before parameter detail, and the dense filter list earns its length by mapping enum values to human-readable meanings. Some enumeration duplicates the schema's enum and the closing sentence about linking product names is presentational rather than invocation-critical, so it is slightly longer than necessary.

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?

For a 6-parameter read tool with an output schema, the description covers query strategy, filtering, sorting, promotion semantics, and per-query return shape. Residual gaps are minor: no mention of empty-result behavior, result truncation beyond the limit cap, or whether queries are matched independently.

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 coverage is 100%, so the baseline is 3. The description does add real meaning on top of the schema — it glosses filter values ('prijsfavoriet (AH's budget label)', allergen categories), clarifies 'most_bought (by this user)', and explains the bonus interplay — but limit and include_images are only restated from the schema rather than expanded.

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 ('Search Albert Heijn products by keyword') with scope detail (multi-query, max 10). It explicitly distinguishes itself from the closest sibling by explaining that bonus=true surfaces volume-discount promotions that ah_get_bonus_offers does not list, so an agent can route correctly without opening schemas.

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

Usage Guidelines4/5

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

Gives concrete when-to-use signals: prefer Dutch search terms with worked examples, use bonus=true for promotion-only results, combine filters for narrowing, choose sort for ordering. It names one alternative (ah_get_bonus_offers) and its exclusion, but does not position itself against ah_get_products or ah_get_product_alternatives, which would be needed for a 5.

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