Live prices, deals & optimal multi-stop shopping routes for German grocery & drug stores.
Scored across 2 tools
The two tools are wholly distinct: plan_optimal_shopping_route creates a new route from a list and start location, while swap_route_item modifies an existing route by swapping one offer for an alternative. There is no functional overlap, and the descriptions explicitly delineate when to use each.
Both tool names follow the same snake_case convention and begin with an imperative verb ('plan_', 'swap_'). The object phrases are descriptive and clearly indicate the action's target, making the naming pattern predictable and consistent.
With only two tools, the server feels on the thin side for a shopping assistant. Although the two tools cover the primary planning-and-adjustment workflow, a broader surface (e.g., browsing offers or fetching store details) might be expected, but the current count is borderline acceptable for the focused scope.
The core lifecycle is covered: plan a route and then swap items on that route. Minor gaps exist—such as not being able to add new stores or adjust the list without replanning—but these can be worked around by calling plan_optimal_shopping_route again, so agents can complete typical tasks without dead ends.
Plans the optimal shopping trip for a given list and starting location in Germany. Answers 'where should I go to buy this list, and is the trip worth it?' — not 'what's on offer near me'. Matches each item on the list to the best current offer across German supermarkets and drug stores (REWE, Aldi, Lidl, Penny, Netto, Norma, Edeka, DM, Rossmann, Mueller, Globus), then computes the cheapest realistic route by weighing product prices against travel distance and shopping time. Returns the chosen store(s), the per-item picks with live prices, the trip's savings and a worth-it Supports car, bicycle, and pedestrian travel modes. For corridor trips (A-to-B), supply 'end_location' to route stores along the way. Pricing note: 'price' is the standard shelf price available to all shoppers (do NOT say discounts require an app). 'app_credit' is optional wallet cashback (e.g. REWE Bonus: plus €0.50 into wallet). 'app_price' is an app-exclusive checkout price (e.g. Lidl Plus).
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | The shopping list in natural language (e.g. '3x milk, eggs, bread') | |
| km_cost | No | Travel cost penalty per kilometer (forced to 0.0 for bicycle/pedestrian) | |
| location | Yes | Starting location (ZIP code, city, or address in Germany) | |
| hour_cost | No | Time cost penalty in EUR per hour (defaults to 12.0) | |
| max_stores | No | Maximum number of candidate stores to evaluate for the route (default: 100) | |
| travel_mode | No | Travel mode to use | car |
| end_location | No | Optional destination location if not a round trip | |
| max_radius_km | No | Maximum search radius in kilometers (defaults: car=15km, bicycle=5km, pedestrian=2km) | |
| shopping_time_per_store | No | Base shopping minutes spent per store (defaults to 10) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description substantially expands on the annotations by explaining how the tool works: matching items to offers across named retailers, weighing prices against travel distance and shopping time, and returning store choices plus per-item picks. It also adds crucial pricing semantics, clarifying that 'price' is the shelf price available to all shoppers and what app_credit and app_price mean. This aligns with the readOnlyHint and gives agents useful behavioral context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative, with purpose front-loaded and behavioral notes sensibly grouped. The list of store names and the pricing clarification earn their place for agent decision-making. There is a minor formatting issue ('worth-it Supports') that slightly harms polish, but no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with nine parameters, the description covers the decision criteria, return contents, travel modes, corridor-trip behavior, and pricing semantics. An output schema exists and the parameters are fully documented in the schema, so the description does not need to restate those. The agent has enough context to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the description adds value on top by clarifying travel modes ('Supports car, bicycle, and pedestrian travel modes') and the purpose of end_location for corridor trips. It does not re-explain every parameter, which is appropriate given the schema already documents them fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it plans an optimal shopping trip for a given list and starting location in Germany. It actively differentiates itself from a nearby concern ('not what's on offer near me') and enumerates the exact decision it answers. This makes the tool's purpose unmistakable and distinct from its sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when the user wants to know where to buy a list, whether the trip is worth it, and which route is cheapest. It also gives a conditional usage instruction for corridor trips ('supply end_location'). However, it does not explicitly contrast itself with the sibling swap_route_item, so the when-to-use versus alternatives guidance is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Swaps one item's chosen offer on an existing shopping route (from a prior plan_optimal_shopping_route result) for one of its alternatives, then returns the RECOMPUTED route with corrected costs and the honest worth-it verdict. Use this to correct a poor pick (e.g. the engine matched a soup hen instead of a roasting chicken) or to take a cheaper/better option the agent spotted in the item's 'alternatives'. The alternative may be at the SAME store or at ANOTHER store ALREADY ON THE ROUTE — it must be the same item category, and its store must already be a stop (no new stores; for that, call plan_optimal_shopping_route again). Keys on stable offer ids: pass the current item's offer_id and the target alternative's offer_id (both taken verbatim from the prior response's products_to_buy / alternatives). The shared route (share_url) is updated in place so the interactive map reflects the swap.
| Name | Required | Description | Default |
|---|---|---|---|
| share | Yes | The share_url (or its 8-char id) returned by plan_optimal_shopping_route | |
| alt_id | Yes | offer_id of the alternative to swap in (from that item's 'alternatives') | |
| offer_id | Yes | offer_id of the item currently on the route (from products_to_buy) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely new behavior: the shared route (share_url) is updated in place so the interactive map reflects the swap, and the return is a full recomputation. It does not discuss failure modes (e.g. invalid/cross-category offer ids), so not 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and return, then constraints and keying; every sentence carries information. It is dense and parenthetical-heavy, but no sentence is disposable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return structure needn't be explained, and the description still adds the constraint set (same category, existing stop only, stable offer ids) and the in-place mutation side effect. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 provenance the schema lacks: offer_id comes verbatim from products_to_buy, alt_id from the item's 'alternatives', and share accepts a share_url or its 8-char id. The category and same-route-store constraints on alt_id are also stated only in prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (swap) and resource (one item's chosen offer on an existing shopping route), and scopes it to what gets returned (the recomputed route with corrected costs and verdict). An agent can distinguish this from plan_optimal_shopping_route, which builds routes rather than editing them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use triggers (correct a poor pick, take a cheaper/better spotted alternative) and an explicit when-not with the correct alternative tool ('no new stores; for that, call plan_optimal_shopping_route again'). Nothing 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
plan_optimal_shopping_route5 fields changedInput schema / properties / max_stores / descriptionPrevious value: -"Maximum number of store stops to allow in the route (default: 100)"New value: +"Maximum number of candidate stores to evaluate for the route (default: 100)"Output schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -trueswap_route_item4 fields changedOutput schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "type": "string"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -trueswap_route_itemplan_optimal_shopping_routeWhere to buy a whole grocery list today: local prices, per-unit and cross-store comparison.
Turn any shopping list into a ready-to-checkout grocery cart across 26 European supermarkets.
Shopping search across 100M+ products, with every retailer's offer and live price in one place.
Live Dutch supermarket prices and promotions (Albert Heijn, Jumbo, Lidl, Aldi and more) for AI.
Add one secure layer between your agents and this server.
