SuperMCP

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

Annotations are readOnlyHint=true and openWorldHint=true, but the description adds critical behavioral context: catalogSize/catalogVisibility are 'reported here only when already known' and 'never waits on the item count'. It explains null semantics and that they are not interchangeable, and warns against misinterpreting null. No contradiction with annotations.

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 5 sentences, front-loaded with what the tool returns and key use cases. It is content-rich without being verbose. Minor improvement could be combining the last two sentences about null handling, but overall it's well-structured 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?

Without an output schema, the description covers all expected return fields (fee bands, minimum order, service area, provenance) and explains edge cases (null values for catalogSize/catalogVisibility). It also references a sibling tool for when a reliable count is needed. This is complete for an AI agent to understand and use 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?

Only one parameter (service_slug) with 100% schema coverage. The description adds extra context: 'Take the slug from a plan's serviceSlug' and provides an example ('shufersal-online'). This gives the agent explicit guidance on how to source the parameter value, going beyond the schema's description.

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 clearly states the tool returns 'full published terms for a single online storefront' including specific details (fee bands, minimum order, service area, provenance). It distinguishes from siblings by specifying it's for a single storefront and gives example use cases like explaining a deliveryFee from optimize_delivery. The name is also clear.

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?

Explicit guidance: 'Use to explain a deliveryFee an optimize_delivery plan reported, or to answer what do I need to spend for free delivery?' It also tells when not to use it (e.g., never read a null as an empty shop) and directs to list_delivery_options for a reliable count. This clearly differentiates from siblings.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds significant value by explaining the semantics of 'orderable: false', clarifying that it means no storefront prices and that the product cannot be bought through this API. It also warns against misrepresenting catalogue identity as availability. No contradiction with annotations.

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, each earning its place. The first sentence states the purpose and scope, the second gives usage guidance, and the third explains a critical behavioral nuance. No fluff or repetition.

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 complexity (two parameters, no output schema), the description adequately covers the return structure by mentioning 'chain-specific item code, display name, and package size' and the orderable flag. However, it does not explicitly describe the top-level product fields (e.g., id, gtin) or the overall shape of the response. Slightly incomplete for a fully self-contained description.

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 baseline is 3. The description adds 'by product_id (UUID) or GTIN barcode', but the schema already describes each parameter with similar clarity (e.g., gtin: 'GTIN/barcode, used only if product_id is omitted'). The description does not add meaningful new semantics beyond the schema.

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 'Fetch full detail for one canonical product by product_id (UUID) or GTIN barcode, including every per-chain listing.' This is a specific verb-resource combination that distinguishes it from sibling tools like search_products.

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?

Explicit guidance: 'Use after search_products to confirm identity, or directly when the GTIN is already known.' It also provides clear instructions on interpreting orderable: false, telling the agent when not to present a chain as purchasable.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the description's main behavioral addition is the clarity that the active filter defaults to true and why active=true is useful. The description also specifies ordering by 'soonest end date,' which adds useful behavioral context beyond annotations. While it could mention rate limits or data freshness, the core traits are well-covered.

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 concise sentences with zero redundant words. It front-loads the core action and examples, then adds the critical usage guidance. Every sentence serves a distinct purpose.

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 tool has no output schema, the description compensates somewhat by explaining the promotional examples and ordering. However, it doesn't clearly state that the response includes fields like promotion type, discount amount, or validity period. For a tool with 5 optional parameters and moderate complexity, slightly more detail on what the response contains would be helpful. Still, for a read-only filtered list tool, it is largely 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%, so the baseline is 3. The description adds a usage hint linking to optimize_delivery and shows how to use active=true, but it doesn't add syntax, format, or example values beyond what the schema already provides for each parameter. The description doesn't compensate further; thus, a 3 is warranted.

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 a specific verb ('List') and resource ('promotions'), provides concrete examples of what a promotion looks like ('2 for 30₪', club-member price, second-unit discount), and explains filtering options. This effectively distinguishes the tool from siblings like get_product or search_products, which deal with different resources.

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 explicitly tells when to use this tool: 'to explain why an optimize_delivery line price is lower than list_price.' This directly connects it to a sibling tool (optimize_delivery) and provides clear context for invocation. No other sibling seems to serve this purpose, making the guidance highly effective.

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?

The annotations already declare readOnly and openWorld hints, but the description adds significant behavioral context beyond that. It explains that the tool does not price a basket, describes the meaning of catalogVisibility and confidence fields, and cautions against recommending based solely on delivery fees. This provides deep transparency about the tool's behavior and limitations, going well beyond the annotations.

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 verbose and somewhat redundant. It repeats the pattern for catalogSize, notesRef, and includes the full parameter descriptions again. While each part adds some value, the repetition with the schema and the long-winded explanations (e.g., 'one where we hold a few hundred items cannot fill a normal basket') make it less concise than necessary.

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?

Since there is no output schema, the description compensates by explaining what each returned entry contains (deliveryTerms.confidence, verifiedAt, catalogSize, catalogVisibility) and what those fields mean. It also covers edge cases like missing chains and the use of include_unavailable. The description is complete for understanding the tool's behavior and output without requiring external knowledge.

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 the description repeats the exact same parameter descriptions as in the schema. It does not add any new meaning or examples beyond what's already provided. Since coverage is high, the baseline is 3, and there is no extra semantic enrichment.

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's purpose: it lists storefronts that deliver to a given address, with delivery terms like fees and minimum orders. It also distinguishes it from the optimize_delivery tool, which is used for pricing baskets. This is a specific verb + resource with clear differentiation from siblings.

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 explicitly says 'Use for who delivers to me?' and contrasts with 'what will my shopping cost delivered?' for optimize_delivery. It also advises to use optimize_delivery before recommending based on fees alone. This gives explicit when-to-use and when-not-to-use guidance, exceeding simple context.

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?

Annotations only carry readOnlyHint/openWorldHint/destructiveHint; the description carries the full behavioral burden and exceeds it. It discloses the needs_destination status flow, the open-world semantics of catalogVisibility ('partial_index' means WE cannot see the whole shop), trust tiers for deliveryTerms.confidence that gate the whole quotable tariff page, price_feed_stale 'must not be presented as an option', and the continuation-token sequencing. It also warns against silent substitutions ('never silently swap them in') and against quoting assumedDeliveryFee as a real price. Nothing contradicts the read-only/open-world annotations.

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 exceptionally long and front-loaded well — purpose first, usage second, then output semantics, then edge cases. But it repeats content already in the rich schema (e.g., response_detail line-breakdown behavior appears both in the enum description and in the tool body), adding redundancy. It is arguably appropriately sized for a 15-parameter tool with no output schema, but it is not concise; several sentences could be tightened without loss.

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 no output schema present, the description shoulders full responsibility for return-value semantics, and it delivers comprehensively: deliveredTotal vs deliveredComparableTotal ranking, pricedLines/requestedLines coverage checks, catalogVisibility, deliveryTerms.confidence tiers, deliveryFeeIsFloor, meetsMinimum/amountToMinimum, cheapestDelivered/bestSingleOrder/bestVerifiedTerms, nextFeeBreak.worthTopUp, cheaperAlternative, splitOrder reasons, unavailableStores classification, venues/venuesOmitted, handoffUrl and status/continuation values. An agent has everything needed to invoke and interpret the result 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 each of the 15 parameters is already documented — several extensively (the query field's Hebrew requirement, pack_qty vs amount distinction). The description adds value mainly at orchestration level beyond the schema: the continuation-carrying flow ('The shopping list travels inside it'), the response_detail tradeoff tied to comparing items across chains, resolution_mode's preview sequence, and max_split_stores' third-fee tradeoff. This lifts it above the schema-only baseline, though most individual parameter semantics remain the schema's job.

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 opening line — 'Price a whole shopping list at every Israeli online supermarket that delivers to an address, and rank them on what the order actually costs: items + delivery fee + service fee' — states a specific verb, resource and scope in one sentence. It differentiates from siblings by name ('This is SuperMCP's shopping-list tool for online supermarket delivery') and later routes to suggest_similar_products, get_delivery_terms and list_delivery_options for adjacent concerns. The title confirms the same purpose.

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/when-not guidance: 'Call this ONCE with the full list — never price lines separately', 'ASK THE SHOPPER WHERE THEY LIVE BEFORE CALLING, whenever you can get it in the same breath', and 'Only when you cannot ask, or when showing the range now beats a round trip, call with no destination.' It names concrete alternatives per condition (suggest_similar_products for a wrong line, get_delivery_terms for terms, list_delivery_options to enumerate venues) and even specifies re-call conditions ('re-call with response_detail=standard only if you must compare the same item's price across chains').

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?

Even though annotations indicate read-only and non-destructive behavior, the description adds extensive behavioral context: without location prices are absent, fromPrice is not a national price, pricedAtStorefronts=1 indicates a single store, and prices exclude loyalty discounts. It also explains that results are sorted by cheapest unit price first, going beyond what annotations provide.

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 information-dense, covering many critical behavioral nuances. It front-loads the main purpose and pricing rule, then packs in workflow guidance. While every sentence earns its place, the length may make it slightly less skimmable, but the structure is logical and no fluff.

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 tool's complexity (11 parameters, pricing semantics, location dependence, cross-store considerations), the description is remarkably complete. It covers how to quote prices, how to compare unit prices, and when to use alternatives. The absence of an output schema is compensated by describing key output fields (pricedAtStorefronts, normalizedUnitPrice) and their interpretation.

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 descriptions in the schema are quite detailed (e.g., location resolution, aliases, radius_km defaults). The description adds critical meaning to the city/location/price interaction (without location no pricing), and clarifies how fromPrice and normalizedUnitPrice should be used, which enhances parameter understanding beyond schema alone.

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 that the tool searches the canonical product catalog by free text, brand, category, or GTIN and answers 'how much is X' for a single item. It distinguishes itself from sibling tools like get_product (which returns listings) and optimize_delivery (for whole lists), and explains its unique pricing behavior.

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 explicit when-to-use guidance: for single-item price queries, and explicitly says not to use for a whole shopping list (use optimize_delivery instead). It also gives a specific workflow for handling wrong pricing via suggest_similar_products followed by optimize_delivery again, and warns against comparing on fromPrice or summing prices.

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?

The description discloses extensive behavioral details: it only splits when delivery fees are verified, reports assumptions for unverifiable counts, handles pack quantities correctly, and clarifies that a null splitOrder means a single order is better. It goes far beyond the annotations (readOnly, openWorld, non-destructive) by explaining side effects and edge cases.

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 excessively verbose and repetitive, with phrases like 'Every fee is a published one' and 'Every leg meets its own storefront's minimum order' stated multiple times. It could be condensed to a few sentences without losing meaning, harming readability and maintainability.

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 verbosity, the description is thorough: it covers purpose, usage conditions, behavioral edge cases, assumptions reporting, return value semantics (splitOrder), and comparisons to the sibling tool. It effectively addresses all relevant contexts for a developer integrating this 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?

While the schema already covers 100% of parameters with detailed descriptions, the tool description adds useful cross-reference context (e.g., items are 'same shape as optimize_delivery') and reinforces the intent parameter's purpose. This supplements the schema without duplicating it.

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's core action: splitting a shopping list across multiple stores and evaluating savings vs. a single order. It distinguishes from sibling tools by referencing optimize_delivery, though the added caveats and repetitive phrasing slightly dilute the clarity.

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 instructs when to use this tool: only when the shopper asks about splitting specifically, or to raise max_stores beyond the default. It also states optimize_delivery returns the same splitOrder field, providing a clear alternative and preventing misuse.

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?

Annotations (readOnlyHint=true, openWorldHint=true, destructiveHint=false) are consistent. The description adds substantial behavioral context: results sorted by cheapest per unit, 'rejected' field has same fields for comparison, fromPrice is a floor across storefronts, pricedAtStorefronts=1 meaning single shop price, and the requirement to send city/address for price reporting. No contradictions.

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?

Description is front-loaded with purpose and example, and each sentence adds value. However, it is fairly long (multiple paragraphs) and could be more structured (e.g., bullet points for the pricing rules). Still efficient given the complexity of the tool's behavior.

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 7 parameters, no output schema, and only basic annotations, the description fully covers the tool's context: usage scenario, workflow steps, result interpretation, pricing caveats, and required parameters for price reporting. No significant gaps remain.

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% (baseline 3). The description adds critical semantic constraints beyond the schema: the query must be in Hebrew (original line or correction), product_id must be the rejected one from optimize_delivery, and city or address is required for price reporting (conditional requirement not in schema). Also explains the meaning of pricedAtStorefronts. This extra value justifies a 4.

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's purpose: to suggest similar products when optimize_delivery priced the wrong product. It specifies the verb ('suggest similar') and the resource ('products'), and distinguishes itself from siblings by explicitly stating it is not for first-pass shopping lists, contrasting with optimize_delivery.

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 explicit when to use (after optimize_delivery wrong pricing), when not to use (not for first-pass lists), and includes an example workflow with a specific alternative ('Then call optimize_delivery again'). It also gives detailed guidance on interpreting results (compare normalizedUnitPrice, not fromPrice).

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