Swissgroceries MCP

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

With no annotations, the description carries the burden and does disclose a key behavioral trait: not all chains support per-store stock queries and unsupported chains return a clear error — a failure mode the agent needs before calling. It does not cover return shape (whether the result is stores with boolean stock or counts) or any rate/permission concerns, keeping it below 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?

Three sentences plus two example phrases, with the core capability front-loaded and the unsupported-chain caveat before the illustrative queries. No sentence is redundant.

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 four-parameter read tool with no output schema and no annotations, the description covers purpose, filtering options, and the unsupported-chain error path. The one gap is that it does not say what the response contains (per-store availability flags versus summaries), which would help the agent interpret results.

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 description coverage is 100%, so chain, productId, near variants, and storeId precedence are all fully documented in the schema. The description only restates that proximity filtering is optional and a single store can be queried by ID, adding no syntax or constraint detail beyond the structured fields — baseline 3.

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 — checking which stores of a given chain have a specific product in stock — and the examples anchor it to a concrete question shape. It is clearly distinguishable from find_stores (store listing) and search_products (product lookup) because the output is a stock-availability intersection of the two.

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 concrete usage contexts ("is this product available near Zurich HB?", "which Coop has item X in stock?") and explains the optional proximity filter versus the single-store-by-ID path. It stops short of explicitly routing away from siblings (e.g. "use find_stores to list branches without stock data"), so it is clear but not exhaustive.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose the returned fields and a data-availability caveat ("opening hours where available"); however, it says nothing about result limits, pagination, behavior when geocoding fails, or rate constraints from the Nominatim dependency for a lookup that is clearly a read operation.

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?

Four tight sentences, front-loaded with purpose, then inputs, then outputs, then usage examples. Every sentence contributes information an agent needs and there is no filler or repetition of the tool name.

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?

With three parameters, full schema coverage, no output schema, and no annotations, this description does the right amount of work: it explains the accepted input modes and enumerates return fields since no output schema exists. The remaining gap is failure and limit behavior, which an agent would want for a search that can silently return empty results.

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 schema already documents all three parameters including the anyOf location forms and the Nominatim note. The description restates the accepted input modes and the chain/radius filters but adds no format, precedence, or behavior detail beyond what the schema says — baseline 3 applies.

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 ("Find grocery stores near a location") plus the two filters (chain, radius), which is enough to distinguish it from search_products, find_stock, and get_promotions without opening a schema. The scope is explicit and there is no ambiguity about what the tool returns.

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?

Provides concrete invocation examples ("find a Migros near me", "which Coop branches are in 8001?") and a sequencing hint — "before checking stock" — which implicitly routes to find_stock. It stops short of naming the alternative tool explicitly or stating when not to use it (e.g. when you already have a store ID).

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that responses include a cached-data signal (fromCache) and a timestamp (fetchedAt), which tells the agent data may be stale. It does not state behavior for unknown/invalid product IDs or any auth/rate constraints, leaving one real gap.

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?

Purpose comes first, then return shape, then how to get IDs, then example phrasings — a sensible front-loaded order. Slightly padded by the enumerated field list and two example utterances, but nothing is genuinely wasteful.

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?

No output schema exists, so the description correctly compensates by naming the top-level response fields and the product payload. For a simple two-parameter lookup this is nearly complete; only error/miss behavior is unaddressed.

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% and both parameters are already documented with the chain enumeration and ID provenance, so the schema does the heavy lifting. The description reinforces the pairing constraint (ID is chain-specific) but adds no format or validation detail beyond that. Baseline 3 applies.

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?

Opens with a specific verb and resource ("Fetch full product details for a specific chain + product ID pair"), which immediately separates it from the listing-style sibling search_products. The scope is unambiguous: one chain/product pair, full detail rather than search results.

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?

Explicitly routes the agent through search_products to obtain IDs and frames the tool as the drill-down step after a search, with two concrete example utterances. It stops short of stating exclusions (e.g., don't use this to browse or to look up stores), but the sequencing guidance is clear.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' clearly implies a read-only operation and the description discloses the returned fields, but it says nothing about result volumes, pagination, whether 'current' means strictly active-now, or freshness/caching of the aggregated chain data. That is a real gap for a multi-source scraper-style tool, though the core read-only nature is clear.

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?

Three sentences: purpose, filter dimensions, return shape, then example queries. The purpose is front-loaded and every clause adds routing or selection value; nothing is redundant filler.

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 read-only, four-optional-parameter lookup with no output schema, the description covers purpose, filters, and return fields, which is most of what an agent needs. It stops short of describing result-set size or ordering behavior, which would matter when combining with plan_shopping or search_products.

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 description coverage is 100%, so all four parameters (query, chains, storeIds, endingWithinDays) are already documented in the schema, including the coopcity opt-in nuance and the find_stores pointer. The description restates the filter dimensions in its own words but adds no format or semantic detail beyond the schema, so baseline 3 applies.

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 opens with a specific verb+resource+scope: 'List current promotional deals across configured Swiss grocery chains.' It also states the return fields (name, discount, validity dates, stores), so an agent knows exactly what the tool produces. No sibling tool overlaps with promotions, so no differentiation is needed.

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?

Three concrete example queries ('what is on sale this week?', 'any Migros deals on cheese?', 'promotions ending today') make the intended use cases unambiguous. It lacks explicit when-not guidance or direction to an alternative tool for non-promotion queries, but the positive routing signal is strong.

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

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

With no annotations, the description carries the burden. It discloses that probing uses a trivial query and reports status/latency/flags, plus timeout defaults, but omits whether the operation is read-only/non-destructive, any auth or cost implications, and how many adapters are hit by default.

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, front-loaded with what it does followed by when to use it. No wasted words.

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 no-annotation, no-output-schema diagnostic tool, the description compensates by describing the return payload (status, latency, capability flags) and the triggering scenarios. Minor gap is the lack of explicit safety/non-destructive confirmation.

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 both parameters (chains, timeoutMs) are already well documented with defaults and bounds. The description adds no meaning beyond the schema, so baseline 3 applies.

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 (probe) and resource (registered chain adapters) and enumerates the reported outputs (status, latency, capability flags). This clearly separates it from data-fetching siblings like find_stores and search_products, though it doesn't name them explicitly.

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 concrete triggering conditions: 'when a chain seems missing from results' or 'when debugging adapter problems.' Clear context, but doesn't explicitly name the alternative data tools or state when NOT to use it.

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

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

With no annotations, the description carries the full burden. It discloses the return shape (primary plan plus alternatives), that items can be generic or SKU-pinned, and how each strategy trades off stops versus cost. It doesn't state that no purchase is made or how expensive the search is, but for a read-only planner the disclosure is solid.

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 purpose and triggering scenarios are front-loaded, followed by the strategy distinctions, with no filler. Every sentence adds either selection guidance or behavioral context.

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 six-parameter planner with no output schema, the description says a primary plan and alternatives are returned but not what those contain (prices, per-store breakdowns, cost estimates). The parameter side is covered by the rich schema, but the return-value side is thin for a tool of this complexity.

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 description coverage is 100%, so the schema already documents every parameter in depth. The description adds little beyond what is in the schema – it restates that items may be generic or pinned and repeats the strategy meanings already given in the enum description. Baseline 3 is correct.

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 gives a specific verb and resource – "Plan a multi-store shopping trip near a location, picking the best products across configured Swiss grocery chains" – which is clearly distinct from sibling tools like search_products or find_stores. An agent can tell this is the multi-store optimizer, not a single-product search or store lookup.

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?

It explicitly states the triggering scenario (a list of items plus "where should I shop?" or "what's cheapest?") and explains the three strategies. It does not explicitly name which sibling to use instead for a single product lookup, but the context is clear enough to route correctly.

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

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

With no annotations, the description carries the full burden and does so: it discloses parallel fan-out across chains, opt-in membership for one chain, grouped-by-chain return shape, per-chain freshness metadata via `sources`, and failure semantics (empty array + `errors` with code/reason on bot protection or outage). That is far beyond what a bare 'search' label would convey.

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?

Core scope and the coop/coopcity distinction are front-loaded, and the examples land at the end as intended. It runs long with several sentences, and the coopcity opt-in rule is stated twice (once outright, once parenthetically), which is mild redundancy rather than waste.

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?

There is no output schema, and the description compensates by characterizing the return shape (`byChain`, normalised price/unit price/size/promotion, `sources` freshness, `errors`). For a 6-parameter nested-filter search tool, nothing an agent needs to call it or interpret results 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 baseline is 3; the description adds real meaning on top by explaining that omitting `chains` searches everything except coopcity, and by characterizing the filter axes (price, size range, tags) that the schema enumerates. It does not add syntax or interaction notes for `limit`/`offset` pagination beyond what the schema documents.

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 ('search for products') plus the exact scope (eight named Swiss grocery chains), and explicitly disambiguates the `coop` vs `coopcity` assortments. An agent can distinguish this from get_product or find_stock without opening any schema.

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 concrete invocation triggers ('find organic milk under 2 CHF', 'compare pasta prices', 'gluten-free bread') and a conditional rule for the opt-in `coopcity` chain. It also instructs the agent to check `errors` before reporting an empty chain, which is a genuine when-to-use-this-and-how caveat.

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