Swissgroceries MCP

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

The description discloses that not all chains support per-store stock queries and that unsupported chains return a clear error. It also mentions that storeId takes precedence over near. With no annotations, the description carries the burden, but it omits details about response format, rate limits, or authentication.

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 three sentences with no redundant information. The first sentence states the core purpose, followed by filtering options and a note about chains. It is front-loaded and efficient.

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?

Given the lack of an output schema and annotations, the description adequately covers the main purpose, filtering options, and chain limitations. However, it does not describe the output returned (e.g., list of stores with availability), leaving a gap in completeness.

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 input schema already describes each parameter in detail. The description adds a high-level summary but does not provide new semantic information beyond what is in the schema, resulting in a baseline score of 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?

The description uses a specific verb 'check' and resource 'stores of a given chain have a specific product in stock'. It clearly distinguishes from siblings like find_stores (which finds stores) and get_product (which gets product info) by focusing on stock availability.

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 provides explicit use cases ('is this product available near Zurich HB?', 'which Coop has item X in stock?') and notes that unsupported chains return a clear error. However, it does not explicitly contrast with sibling 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?

No annotations are provided, so the description carries the full burden. It explains that the tool returns store details including opening hours where available, indicating a read-only operation. However, it does not disclose potential rate limits, authentication needs, or any side effects, which is acceptable for a simple search tool.

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 three sentences: first states purpose, second describes inputs, third summarizes outputs and examples. It is front-loaded with key information, no redundant phrases, and every sentence adds value.

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 search tool with 3 parameters and no output schema, the description adequately covers inputs, outputs, and example usage. It mentions return fields (name, address, chain, location, hours). It could have explicitly stated the default radius, but that is detailed in the schema. Overall, it is sufficiently complete for an agent to use effectively.

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 input schema has 100% coverage with descriptions for each parameter. The description adds minor context (e.g., prefer zip or lat/lng for speed, geocoding via Nominatim) but mostly restates schema information. The baseline score of 3 is appropriate as the description provides some additional guidance.

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 clearly states the tool finds grocery stores near a location with filters for chain and radius, using specific verbs and resource. It also provides example use cases that distinguish it from siblings like find_stock and get_product.

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 concrete examples of when to use this tool ('find a Migros near me', 'which Coop branches are in 8001?') and hints at its role before checking stock. However, it does not explicitly state when not to use it or provide alternatives for non-store queries.

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 bears full responsibility. It discloses the return structure ({ product, fetchedAt, fromCache }), the contents of product (price, brand, etc.), and data freshness (fetchedAt, fromCache). It does not cover authentication or rate limits, but for a read-only operation this is acceptable.

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 two sentences long plus a brief list of return fields, with no wasted words. The most critical information (what the tool does) appears first, and subsequent details are efficiently structured.

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?

Despite lacking an output schema, the description fully covers the return object's shape and semantics. It explains how to obtain input IDs, what the tool does, and how to interpret results. For a two-parameter read tool, this is 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 description coverage is 100% (both parameters have descriptions). The description adds context by explaining where to get IDs ('Obtain product IDs from search_products') but does not significantly extend the schema's own parameter explanations. Baseline 3 is appropriate.

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 uses a specific verb-resource pair ('Fetch full product details') and clearly identifies the scope ('specific chain + product ID pair'). It distinguishes from siblings by noting it is used after search_products and lists alternative fields (price, brand, etc.) that differentiate it from other tools.

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 states explicit use cases ('drilling into a search result', 'get details for this Migros product') and advises obtaining IDs from search_products. It does not explicitly mention when not to use, but the context signals and sibling names imply alternatives (e.g., find_stock for inventory).

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 transparently explains the tool's behavior: it lists promotions, returns specific fields (name, discount, validity dates, stores), and supports filters. It doesn't mention potential limitations like rate limits or authentication, but the 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?

The description is concise (two sentences) and front-loaded: first sentence states the main function and filters, second lists returns and usage examples. Every sentence is meaningful and directly contributes to understanding.

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?

Despite no output schema, the description adequately covers what the tool returns (name, discount, validity dates, applicable stores). It doesn't mention pagination or result limits, but for a promotional listing query, the essential information is provided.

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?

All 4 parameters have schema descriptions (100% coverage). The description adds value by providing concrete examples (e.g., 'Käse', 'wine' for query) and referencing the helper tool find_stores for store IDs, enriching the schema information.

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 clearly states the tool lists current promotional deals across Swiss grocery chains, with a specific verb and resource. It distinguishes itself from sibling tools like search_products (general product search) and get_product (single product details) by focusing on promotions and filtering options.

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 provides explicit usage examples (e.g., 'what is on sale this week?', 'any Migros deals on cheese?'), guiding when to use the tool. It does not explicitly state when not to use it, but the context contrasts well with sibling tools.

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 provided, so description carries full burden. It describes the operation as 'probe with a trivial query' and reports status/latency/capability flags, implying a read-only health check. However, it does not explicitly confirm no side effects, auth requirements, or rate limits. The description is adequate but not rich.

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: first states functionality, second provides usage guidance. No wasted words, front-loaded with key action.

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 diagnostic tool with 2 optional params and no output schema, the description covers purpose, trigger, and high-level output. Could be slightly more detailed on output format, but sufficient.

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% with both parameters documented. The description adds no new meaning beyond the schema, so baseline 3 is appropriate.

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 uses specific verb 'probe' and resources 'chain adapters' and states outputs: status, latency, and capability flags. It also positions it for debugging missing chains, distinguishing it from sibling data tools like search_products or find_stock.

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 states when to use: 'chain seems missing from results' or 'debugging adapter problems'. Does not mention when not to use or contrast with alternatives, but the context with sibling tools makes the purpose distinct.

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 full responsibility. It mentions return of 'primary plan plus alternatives' and strategies, but does not elaborate on side effects, rate limits, or error behavior (e.g., no stores found). It is adequate but not detailed.

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 sentences, front-loaded with purpose, no redundant text. Each sentence contributes context: purpose, item types, usage hint, and strategy options.

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?

Covers high-level purpose, item flexibility, and strategies. However, it lacks details on the return format (no output schema) and does not describe what happens when constraints fail (e.g., no matching products). Still, it is largely complete for a planning tool.

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 all parameters thoroughly. The description adds little new information beyond strategies, making it a 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?

The description clearly specifies the tool's function: planning a multi-store shopping trip near a location, picking the best products across Swiss grocery chains. It distinguishes itself from siblings like find_stock and find_stores, which handle single-store queries or product lookups.

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 states when to use: 'Use when the user gives a list of items and asks "where should I shop?" or "what's cheapest?"' and outlines three strategies. However, it lacks explicit when-not-to-use guidance compared to alternatives.

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 fully carries the behavioral burden. It discloses that results are grouped by chain, includes normalized price and promotion info, and reports data freshness via a sources map with timestamps. It does not explicitly state it is read-only, indicate rate limits, or mention authentication requirements, but the provided details are sufficient for safe usage.

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 sentences efficiently cover purpose, filters, output format, and usage examples. No extraneous words, and key information is front-loaded. Ideal structure for an AI agent to quickly parse.

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 tool with 6 parameters (including nested objects) and no output schema, the description adequately explains the return structure, filter logic, and data freshness. It lacks error handling or edge-case guidance, but the usage examples and parameter details cover typical scenarios. Minor gap in describing limit/offset pagination behavior, but overall 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 100%, so parameters are individually described. The description adds value by explaining how filters combine (e.g., 'All tags must match') and contextualizes the output. However, it does not provide deeper semantic nuance beyond what the schema already conveys. Score reflects the baseline for full schema coverage with modest additive value.

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?

Description specifies the core action 'Search for products' and the exact resource scope: 'across configured Swiss grocery chains (Migros, Coop, Aldi, Denner, Lidl)'. It provides concrete example queries like 'find organic milk under 2 CHF', which help distinguish this tool from siblings like get_product (single product lookup) and find_stock (inventory check).

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 lists explicit use cases ('Use for ...') and demonstrates how to combine filters. It implies the tool is for cross-chain price comparisons and attribute searches. However, it does not explicitly state when not to use it or differentiate from get_product (single item) and find_stock (availability). The guidance is clear but lacks exclusionary context.

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