SuperMCP

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context by detailing the return contents and provenance of the data. This goes beyond the annotations without contradicting them, giving the agent a clear picture of what to expect from a read-only 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?

The description is concise: three sentences with the core purpose first, followed by usage context and parameter sourcing. Every sentence adds value and there is no 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 simple one-parameter read-only tool with no output schema, the description is remarkably complete: it specifies the exact data returned (fee bands, min order, service area, provenance), the use cases, and how to obtain the required parameter. It fully compensates for the absence of an output schema.

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 schema already has 100% coverage for the single parameter service_slug, but the description adds crucial guidance by instructing the agent to take the slug from a plan's serviceSlug, which is not present in the schema. This adds practical meaning beyond the structured definition.

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 retrieves the full published delivery terms for a single storefront, enumerating the specific contents (fee bands, minimum order, service area, provenance). It also distinguishes itself by tying to a specific use case with optimize_delivery and explaining deliveryFee, differentiating from sibling tools like list_delivery_options or 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 explicitly says when to use the tool: to explain a deliveryFee from an optimize_delivery plan or answer free-delivery threshold questions. It also instructs where to get the slug (from the plan's serviceSlug). However, it doesn't explicitly mention alternatives or when not to use it, so it falls short of the top score.

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 goes beyond the readOnlyHint annotation by specifying what the return includes: 'every per-chain listing (chain-specific item code, display name, and package size).' It does not cover error behavior or edge cases, but with annotations already indicating a safe read, this is sufficient.

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, front-loaded with the primary action, and contains no filler. Every clause adds value: the what, the identifier options, the return detail, and the usage guidance.

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 fetch-by-ID tool with only two optional parameters and no output schema, the description is complete. It states what is fetched, how to identify the product, and when to use it. The mention of per-chain listings gives a concrete sense of the response content.

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 explains the role of each parameter, including that gtin is used only if product_id is omitted. The description reiterates the two identifiers but adds no substantial meaning beyond the schema, 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?

The description starts with a specific verb 'Fetch' and identifies the resource as 'full detail for one canonical product' with two distinct identifiers (product_id or GTIN). It clearly distinguishes from sibling tools like search_products, which is for searching, and get_promotions/get_delivery_terms, which target other domains.

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 names the primary use case: 'Use after search_products to confirm identity, or directly when the GTIN is already known.' This provides clear context and directs the agent to the appropriate alternative (search_products) when the product identity is not yet known.

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 and openWorldHint=true, lowering the bar. The description adds useful context about promotion types and the active filter but does not disclose any additional behavioral traits (e.g., pagination, cost, or specific side effects). It adds value beyond annotations but not richly.

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, zero filler. The first sentence leads with the action and gives examples, the second provides a specific use case. Every clause earns its place.

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 list tool with no output schema, the description covers purpose, filters, and a usage scenario. It might benefit from specifying the response format, but the combination of annotations, schema, and description is largely complete for the task.

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 mentions store_id, product_id, and active, but these are already fully described in the schema. It does not add new parameter meaning beyond what the schema provides.

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 ('List') and noun ('promotions'), provides concrete examples, and notes the optional filters (store_id, product_id, active). It clearly distinguishes the tool from siblings by focusing on promotions and even ties to optimize_delivery pricing, making the tool's role unambiguous.

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 states when to use the tool: 'Use this to explain why an optimize_delivery line price is lower than list_price.' It gives a clear, actionable use case. However, it does not explicitly mention alternatives or when not to use the tool, though the sibling context provides some implicit differentiation.

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 and openWorldHint. The description adds valuable context about data provenance and reliability: each entry carries deliveryTerms.confidence and verifiedAt, and instructs to quote a fee only when verified/reported, otherwise say unknown. This goes beyond annotations, though it doesn't cover all behaviors (e.g., pagination), the read-only nature is already 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 three sentences: the first states the core function and output scope, the second gives usage guidance with an explicit alternative sibling, and the third explains data confidence handling. It is front-loaded, concise, and every sentence earns its place.

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, but the description mentions key entry fields (deliveryTerms.confidence, verifiedAt) and behavior. With 5 optional parameters and no required ones, the description gives enough context for an agent to invoke correctly and interpret results, though a more formal return structure would be helpful.

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 covers 100% of parameters with descriptions, so baseline is 3. The description adds extra nuance: city is sufficient for chains with settlement lists but not for polygon or depot-radius areas, and near must not be combined with address. This provides guidance 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 uses a specific verb 'list' with a clear resource: Israeli online supermarkets delivering to an address, and enumerates the output fields (fee, minimum order, free-delivery threshold, click-and-collect). It explicitly distinguishes from sibling optimize_delivery by noting 'without pricing a basket' and directing users to optimize_delivery for shopping cost.

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 states when to use: 'Use for who delivers to me?' and when not to: 'For what will my shopping cost delivered?, use optimize_delivery instead.' It also provides guidance on handling fees based on confidence and verifiedAt, which helps an agent present results appropriately.

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 goes well beyond the readOnlyHint and openWorldHint annotations by detailing ranking semantics (deliveredComparableTotal vs deliveredTotal), delivery fee confidence levels, fee floors, minimum-order handling, and default line-breakdown behavior. It also flags edge cases like unavailableStores and nextFeeBreak, giving the agent actionable interpretation guidance.

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 richly informative but presented as one dense unbroken block, making it harder to scan. Every sentence carries meaning, but the lack of structure and overall length prevent it from being concise.

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 no output schema, the description compensates by enumerating key result fields (deliveredTotal, deliveredComparableTotal, pricedLines, confidence, assumedDeliveryFee, amountToMinimum, bestSingleOrder, etc.) and explaining default and edge-case behavior. This is a comprehensive explanation for a 13-param 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?

With 100% schema coverage, the schema already documents all 13 parameters and enum options. The description adds usage-level guidance (e.g., full list at once, response_detail re-call) but no additional parameter-specific semantics, 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?

The description opens with a specific verb+resource+outcome: 'Price a whole shopping list at every Israeli online supermarket that delivers to an address.' It also explicitly distances itself from line-by-line pricing ('never price lines separately'), making its scope clear and distinct from the sibling lookup 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 gives explicit invocation rules: call once, never per-line, and re-call with response_detail=standard only when cross-chain comparison is needed. It frames the tool as 'SuperMCP's shopping-list tool for online supermarket delivery,' which implies scope, but it does not name sibling tools as 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so no contradiction. The description adds useful behavioral context beyond annotations: it 'matches chain listing names' and returns 'canonical products (not per-chain detail); call get_product for listings.' This clarifies the tool's output scope and relationship to other tools, enhancing transparency.

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 a bit longer than the TDQS-4.3 example but every sentence carries essential operational information. It is front-loaded with the core purpose and then provides usage boundaries and return-type clarification. No fluff, but it could be tightened slightly without losing 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?

Given the tool's complexity (11 optional parameters, no output schema, competing sibling optimize_delivery), the description is remarkably complete. It explains what the tool returns (canonical products) and when to delegate to get_product or optimize_delivery, covering the main decision points. The annotations plus schema handle parameter details, so the description does not need to repeat them.

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 a meaningful semantic beyond the schema: 'Also matches chain listing names,' which explains that the free-text query goes beyond canonical names. It also explicitly lists search dimensions (free text, brand, category, GTIN) that correspond to parameters, reinforcing their usage without duplicating schema descriptions.

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 action: 'Search the canonical product catalog by free text (Hebrew or English), brand, category, or exact GTIN.' It also distinguishes itself from siblings by noting it returns canonical products and that get_product is for listings. The verb 'search' and the specific search dimensions make the purpose unambiguous.

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 is provided: 'Prefer optimize_delivery with query items for shopping lists — use this only to disambiguate a low_confidence item or when browsing.' It also gives exclusions ('Do not use this for a shopping list or after optimize_delivery has started.') and names an alternative ('Use optimize_delivery directly'). This fully meets the when/when-not/alternatives criterion.

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