ah_get_categoriesRetrieves top-level Albert Heijn supermarket product shelves and categories—such as produce, bakery, and dairy—with results cached for up to 24 hours.
Get top-level supermarket product shelves and categories (e.g. Aardappel/groente/fruit, Bakkerij, Zuivel). Cached for up to 24 hours.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections.
v0.2.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds a genuine behavioral trait beyond them: results are cached for up to 24 hours, which matters for freshness expectations. It doesn't cover auth requirements or return shape, but for a read-only lookup the caching note is meaningful added context.
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 tight sentences: purpose and examples first, caching caveat second. No filler, nothing buried.
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 zero-parameter, read-only lookup with no output schema, the description covers purpose, sample values, and caching behavior – enough to call it correctly. Explicit routing relative to ah_get_sub_categories would complete it.
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?
The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument listing call and introduces no parameter confusion.
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 and resource ('Get top-level supermarket product shelves and categories') and gives concrete examples (Aardappel/groente/fruit, Bakkerij, Zuivel). The word 'top-level' distinguishes it from the sibling ah_get_sub_categories without ambiguity.
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 'top-level' framing implies this tool is the entry point before drilling into ah_get_sub_categories, but the description never explicitly names that sibling or states when to prefer it over ah_search_products. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.