ah-mcp

Albert Heijn: Search Products

ah_search_products

Read-only

Search Albert Heijn products by keyword, filter by dietary needs or promotions, and sort results. Supports up to 10 queries per call.

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. 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, image_url. When you mention a product or recipe from the result, link its name to its url.

Input Schema

TableJSON 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)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`searches`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.3.1Oct 5, 2026

addedInput schema / properties / filters

Added value: +{
+  "description": "Only products matching all of these, e.g. [\"organic\", \"vegan\"]",
+  "items": {
+    "enum": [
+      "organic",
+      "prijsfavoriet",
+      "new",
+      "frozen",
+      "vegan",
+      "vegetarian",
+      "low_sugar",
+      "low_fat",
+      "low_salt",
+      "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"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / sort

Added value: +{
+  "description": "Result order (default relevance)",
+  "enum": [
+    "relevance",
+    "price_low_high",
+    "price_high_low",
+    "most_bought",
+    "nutriscore"
+  ],
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "searches": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "error": {
+            "type": "string"
+          },
+          "query": {
+            "type": "string"
+          },
+          "results": {
+            "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": [
+          "query",
+          "results"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "searches"
+  ],
+  "type": "object"
+}

First observedv1.0.0Oct 5, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations only declare readOnlyHint=true, so the description usefully adds the max-10-query constraint, the default limit behavior, the promotion-only toggle, and a per-query result field list plus a presentation instruction (link product names to their url). It adds real context beyond the safe-read annotation, though it doesn't cover pagination or failure behavior.

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 usage-critical details first. It is somewhat long, and enumerating all 23 filter values duplicates the schema enum rather than only paraphrasing categories, which is mild redundancy.

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?

With an output schema present, return-value explanation is optional, yet the description still lists per-query fields and adds the name-to-url linking instruction. Enough context exists to call the tool correctly; only sibling routing and pagination nuances are absent.

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; the description earns more by explaining filter semantics the enum doesn't (prijsfavoriet = AH's budget label, grouped diet/allergen categories), clarifying sort option 'most_bought (by this user)', and restating the queries cap with worked examples.

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 (Dutch supermarket) products by keyword'), and the keyword-search framing distinguishes it from id-based siblings like ah_get_products and from ah_search_recipes.

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 clear operating guidance — pass one or more queries (max 10), prefer Dutch terms, use bonus=true for promotions, and how filters combine (AND semantics). It does not explicitly contrast with siblings such as ah_get_products or ah_get_bonus_offers, so no true when-not guidance.

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