Fetch a paginated list of every product from one Dutch supermarket retailer by slug, such as albert_heijn or jumbo.
Every product from one retailer, paginated. Takes a retailer slug (albert_heijn, jumbo, aldi, lidl, ekoplaza, plus, dekamarkt, hoogvliet, vomar, dirk), not a display name.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| retailer | Yes | ||
| page_size | No | Items per page |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description is freed to add the details annotations cannot: that results are paginated and that the key must be a slug. No rate limits or ordering behavior are disclosed, but the added correctness detail is real.
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?
Two sentences, zero filler, front-loaded with what the tool returns before the parameter caveat. Every clause earns its place.
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 simple read-only paginated listing with no output schema, the description covers result scope, identifier format, and pagination. It lacks any indication of ordering or how this fits among the many other product/deal siblings, which keeps it from being fully complete.
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 only 67%, and the required 'retailer' param has no schema description and no enum. The description compensates by enumerating the ten valid slugs and warning it is a slug, not a display name — meaning an agent could construct a valid call without guessing. This is exactly the value the schema omits.
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+resource with scope: 'Every product from one retailer, paginated.' This is distinguishable from generic siblings like pp_list_products or pp_search_products_by_name because the retailer scoping is explicit. It stops short of naming which sibling to use instead when no retailer filter is wanted.
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?
Usage is implied by 'from one retailer' — call it when you want everything for a single retailer — but there is no explicit when-to-use/when-not guidance and no alternative sibling is named (e.g., pp_list_products for a cross-retailer listing). Implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.