SuperMCP

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

Annotations already establish it as a read-only, non-destructive, open-world lookup, but the description adds real behavior: it answers from published terms and never waits on the item count, and it explains that a null catalogSize/catalogVisibility has two non-interchangeable meanings. That null-handling contract is the kind of detail annotations cannot convey. It stops short of describing pagination or freshness/latency of the published terms.

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?

Front-loaded with the purpose, then usage, then the caveat about nulls; every sentence carries information. It is somewhat dense and the null discussion runs long, but nothing is 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?

No output schema exists, so the description carries the return-value burden and does so: it names the returned fields, their provenance, and the semantics of null catalog fields. An agent has enough to call 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?

With 100% schema coverage and a single required parameter, the schema already documents service_slug including the 'shufersal-online' example. The description's 'take the slug from a plan's serviceSlug' restates the schema rather than adding new syntax or constraints, 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 and resource ('the full published terms for a single online storefront') and enumerates the payload (fee bands, minimum order, service area, provenance), which cleanly separates it from list_delivery_options and 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?

Gives two concrete use cases (explaining a deliveryFee from an optimize_delivery plan, answering the free-delivery threshold question), names the alternative for counts (list_delivery_options), and warns against the wrong inference from a null.

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 cover the read-only/open-world safety profile; the description goes well beyond that by decoding the `orderable` flag, warning that a listing is catalogue identity rather than availability, and forbidding presenting an `orderable: false` chain as purchasable. Since no output schema exists, this is the only place that semantics is disclosed.

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?

Front-loads purpose and the routing rule before the longer `orderable` explanation, and every sentence carries real meaning. Slightly long, and the final aggregate sentence partially overlaps the earlier warning, but nothing is 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?

With no output schema and zero required parameters, the description supplies exactly what is missing: the shape of the response (per-chain listings with item code, name, package size) and the interpretation of the `orderable` flag. An agent can call and correctly use the result without further context.

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 schema already documents the UUID format and the precedence rule ('used only if product_id is omitted'). The description restates the same keys and formats without adding new syntax or constraints, so the 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?

Names a specific verb and resource ('Fetch full detail for one canonical product') and identifies both lookup keys (product_id UUID or GTIN barcode). It also lists the returned content (per-chain listing with item code, display name, package size), which separates it cleanly from 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?

Explicitly states when to call it: 'after search_products to confirm identity, or directly when the GTIN is already known.' The sibling tool search_products is named and the condition selecting this tool over it is spelled out.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the semantic point that promotions explain discounted line prices, but says nothing about result ordering, pagination, or data freshness beyond what the schema already states.

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 with the resource and filters front-loaded; the parenthetical examples earn their space by clarifying promotion kinds. Slight redundancy with schema-documented filters keeps it just below a perfect score.

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 bears some burden for return semantics; the parenthetical promotion examples and the list_price linkage give an agent enough to interpret results. It could still say more about the shape of returned promotions, but combined with full schema coverage and read-only annotations it is adequately 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% and parameters are well documented there (city semantics including chain-wide promotions, limit defaults/max, active default). The description merely restates store_id, product_id and active, adding no syntax or interaction 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?

States a specific verb and resource ('List promotions') and immediately grounds it with concrete examples of promotion types ('2 for 30₪', club-member price, second-unit discount). The cross-reference to optimize_delivery line price vs. list_price lets an agent place this tool relative to a sibling 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 a clear trigger scenario: use it to explain why an optimize_delivery line price is below list_price, and names the sibling involved. It stops short of stating when NOT to use it or naming alternative lookup paths (e.g. get_product), so it is strong context without full exclusion guidance.

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 cover the safety profile (readOnly, non-destructive, openWorld), but the description adds substantial behavior the annotations do not: confidence/verifiedAt gating on quoted fees, the meaning of catalogVisibility 'partial_index' vs 'full_catalogue', notesRef/sharedNotes indirection, and the chain-level deduplication of venue terms. This is exactly the extra context the low annotation bar rewards.

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 routing rule and the fee-confidence caveat are front-loaded ahead of the data-model explanation, which is good ordering. The description is dense and long, but nearly every sentence carries a distinct operational instruction rather than 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?

There is no output schema, so the description must carry return-value semantics — and it does, documenting confidence, verifiedAt, catalogSize, catalogVisibility, notes/notesRef and sharedNotes. Combined with the safety annotations, an agent has everything needed to call and interpret 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?

Schema description coverage is 100% and each parameter already explains its own tradeoffs (city limitation for polygon areas, 'do not combine with address', chain filter returning no options). The description adds nothing parameter-specific, so the baseline of 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+resource ('Which Israeli online supermarkets deliver to an address') and enumerates exactly what each entry carries (fee, minimum order, free-delivery threshold, click-and-collect), while explicitly noting it does NOT price a basket. It is cleanly distinguishable from optimize_delivery, which is named directly.

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 an explicit trigger phrase ('who delivers to me?') and an explicit routing rule for the sibling: 'For what will my shopping cost delivered?, use optimize_delivery instead.' It goes further by warning never to recommend on fee alone and directing the agent to price the basket with optimize_delivery first.

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 cover only the read-only/open-world profile; the description discloses far more — the needs_destination status and why it is not a recommendation, the confidence gating that nulls deliveryFee/freeDeliveryThreshold/nextFeeBreak together, priceFeedStale and price_feed_stale semantics, default lines:[] behavior, and the rule that venue rows must never be quoted. This is exactly the beyond-annotations context the dimension rewards.

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?

Front-loaded correctly, but it runs to roughly a thousand words of undifferentiated prose with no headings or grouping — return-shape detail, fee-gating rules, split-order logic and handoff advice all in one block. Much of it is valuable, but the size imposes a real context cost and many sentences do not earn their place at this length.

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 15 parameters, no output schema and no required fields, the description carries the whole burden and does: it documents deliveredTotal vs deliveredComparableTotal, plans vs unavailableStores, venues/venuesOmitted, splitOrder reasons, and the handoffUrl handover. An agent has what it needs to call and to interpret the reply.

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 3 is the floor, but the description adds interaction semantics the schema cannot express: continuation travels with answers or with the city/address 'and nothing else', response_detail controls which plans carry a lines breakdown, and resolution_mode's preview is a two-call protocol. Individual field meanings are left to 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?

Opens with a specific verb and resource — price a whole shopping list at every Israeli online supermarket that delivers to an address, ranked on items + delivery fee + service fee. It also positions itself against siblings by naming list_delivery_options, get_delivery_terms and suggest_similar_products in the flow of guidance, so an agent can tell what this tool owns versus what they own.

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 routing conditions throughout: pass the full list in one call rather than pricing lines separately; send {continuation, city} or {continuation, address} to resume; use response_detail=standard only when comparing the same item across chains; use preview on long or unusual lists; never backfill a withheld fee from get_delivery_terms; call suggest_similar_products then re-call this tool when a line is rejected. Alternatives and exclusions are both stated.

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 declare readOnly/openWorld/non-destructive; the description adds substantial behavior the annotations cannot carry — pricing only exists when a location is supplied (otherwise price fields are absent), fromPrice is a per-storefront floor rather than a national rate, pricedAtStorefronts=1 is a single shop, fromPrice excludes loyalty/coupon rates, and results are sorted cheapest per unit. These are exactly the non-obvious traits that would cause misquoting or double-counting.

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 and the pricing caveat are front-loaded, and nearly every sentence carries decision-relevant content. It is nonetheless a dense paragraph that restates the 'not one national price' warning in several forms and could be trimmed without losing meaning, so it falls short of a 5.

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, the description must carry the return contract and does: canonical products rather than per-chain detail, on what basis hits are ordered, which price fields appear and when, and how to interpret fromPrice versus normalizedUnitPrice. Nothing an agent needs to call this correctly or interpret the response 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 the baseline is 3; the description earns an extra point by explaining the cross-parameter consequence the schema does not state — supplying city or address causes every hit to return price fields, and their absence is explained by 'without a location nothing can be priced'. It does not elaborate radius_km, store_id, limit, or the near/location exclusion beyond what the schema already says.

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 the canonical product catalog) plus the exact matching modes (free text Hebrew/English, brand, category, exact GTIN) and explicitly distinguishes itself from get_product ('Returns canonical products (not per-chain detail); call get_product for listings'). An agent can separate it from every sibling without opening another 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 explicit when-to-use, when-not-to-use, and named alternatives: use optimize_delivery ONCE for a whole shopping list rather than pricing lines here, and use suggest_similar_products with the shopper's Hebrew words plus the rejected product_id after a mismatch, then re-call optimize_delivery. Failure-recovery routing is spelled out, not implied.

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?

Goes well past the readOnly/openWorld annotations: it discloses the fee-verification policy (a leg with unverified delivery fee is never offered), the two reason values and their cost semantics, that 'more_of_the_list' yields a negative saving, that each leg gets its own handoffUrl, and that every leg independently meets its storefront minimum. This is real behavioral context an agent cannot get from structured fields.

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?

Front-loaded with the shopper question it answers, then behavior, then routing. It is dense and occasionally repetitive ('Say which of the two it is', 'Give the shopper both'), but nearly every sentence carries constraint or routing information, so length is mostly earned.

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, the description carries the return-value burden and does: it enumerates the returned constituents, the handoff URLs, the reason discriminator, and the null case. Nothing an agent needs to interpret or act on a result 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 the baseline is 3, but the description adds meaning for max_stores by explaining that a third store introduces a third delivery fee and only wins when it reaches items the other two lack. It also frames items as 'the same shape as optimize_delivery', which helps reuse.

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 question it answers ('can I save by ordering from more than one shop?' for a whole list) plus the concrete outputs (which items where, per-leg subtotal, fees, combined total, savings). It explicitly names the sibling it overlaps with, optimize_delivery, so an agent can separate the two without opening schemas.

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 an explicit when-to-call rule: 'call this one only when the shopper asks about splitting specifically, or to raise max_stores to 3', and notes optimize_delivery already returns splitOrder. It also tells the agent what to do when splitOrder is null — report plainly and point at the single-order recommendation, do not retry.

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 cover the read-only safety profile, so the description goes further with real operational detail: city/address is required or no price can be reported, fromPrice is a storefront floor to be quoted as 'from ₪X', pricedAtStorefronts=1 signals a single-shop price, and results are sorted cheapest per unit. This is substantial context beyond what readOnlyHint/openWorldHint 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?

Purpose and trigger are front-loaded, and nearly every sentence carries information, but the pricing digression (fromPrice vs normalizedUnitPrice economics) is dense and the when-not guidance sits last rather than beside the purpose. Slightly longer than strictly needed.

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 describing the returned fields (fromPrice, normalizedUnitPrice, rejected, pricedAtStorefronts) and their sort order, plus the required geographic input for pricing. For a 7-param workflow tool with no output schema, an agent has everything needed.

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 meaning the schema doesn't, e.g. that query should be Hebrew and that product_id is dropped from results, plus the concrete 'נקניקיות פרגיות → query=פרגיות' mapping. It doesn't explain near/location/radius_km interactions, which are left to 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?

States a specific verb+resource and ties it to a concrete trigger ('After optimize_delivery priced the wrong product, use this to show other things the shopper might have meant'), and explicitly separates itself from the sibling by scope. An agent can identify this tool without opening the 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 explicit when-to-use, a worked recovery workflow (re-call optimize_delivery with the line pinned), an alternative use case ('is there a cheaper one?'), and an explicit when-not: 'Do not use this for a first-pass shopping list — call optimize_delivery once with every line.' Both the alternative and the exclusion are named.

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