buywhere-mcp

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does indicate a read-style operation by saying it 'Returns' data, and it lists the returned fields, but it does not explicitly state that it is read-only, how missing/invalid IDs are handled, or any other behavioral traits such as ordering or limits beyond the schema.

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 short sentences with no filler. The core action is front-loaded, and the returned fields are stated efficiently.

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 single-parameter tool, the description covers the basic purpose and return values, and the schema covers the parameter. However, it does not address the existence of compare_products_v2 or any other routing context, and with no output schema, an agent gets no structural detail about the response beyond the listed fields.

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 already fully documents the only parameter, ids, including type, min/max items, and a description. The tool description adds no additional parameter-level meaning, so the baseline score 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?

The description uses a specific verb and resource, 'Compare multiple products side-by-side,' and lists the returned attributes (price, brand, rating, category). It is clear what the tool does, though it does not distinguish it from the similarly named sibling compare_products_v2.

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 use case is implied: use it when you need to compare multiple products side by side. However, it does not mention when to prefer this tool over alternatives such as get_product, search_products, or compare_products_v2, nor does it state any exclusions.

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 provided, the description carries the full burden of behavioral disclosure. It does disclose meaningful behavior: the tool returns a 'resolved outbound_url per product for the buyer market,' indicating market-specific URL resolution. However, it does not mention side effects, permissions, rate limits, or any caveats about the comparison data, leaving some behavioral transparency gaps.

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 short and front-loaded with the most important requirement, 'REQUIRED deliver_to.' It wastes little space and covers the core purpose, return fields, and a usage reminder. There is minor redundancy between 'REQUIRED deliver_to' and 'Always pass deliver_to...', but overall it is concise and readable.

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 that there is no output schema, the description appropriately explains what the tool returns and ties the return values to the buyer market. It also highlights the required parameter and gives an example value. The main missing piece is explicit comparison or routing guidance relative to the sibling 'compare_products' tool, but for the tool's own operation the description is reasonably 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 schema already documents both parameters. The description reinforces that 'deliver_to' is required and suggests a default value ('SG' or the buyer's country), adding a small amount of practical guidance. It does not add meaningful semantics for the 'ids' parameter beyond what the schema already provides, so the baseline score of 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 states a clear verb and resource: 'Compare multiple products side-by-side.' It also specifies what is returned (price, brand, rating, category, resolved outbound_url), making the tool's function evident. However, it does not explicitly differentiate itself from the sibling tool 'compare_products', so an agent may struggle to pick between the two based on the description alone.

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 a strong instruction about the required 'deliver_to' parameter and says to always pass the buyer's country, which is useful parameter-level guidance. But it gives no explicit guidance on when to use this tool versus alternatives like 'compare_products', 'find_best_price', or 'find_similar'. No when-not-to-use or alternative-selection criteria are mentioned.

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 provided, the description carries the full transparency burden, and it succeeds. It thoroughly discloses the degraded contract, including 200-OK envelopes with meta.degraded=true, null best_price, empty alternatives, and diagnostic fields. It also states that unqualified empty results are never returned for timeouts, auth failures, upstream exceptions, or circuit breakers.

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 front-loaded with the usage trigger, followed by the return format, and then a dense but highly relevant degraded-contract section. Every sentence contributes operational value, and the length is justified by the complexity of the tool's failure 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?

For a tool with no output schema and no annotations, the description covers the return shape, scope, and degraded error behavior quite well. It is slightly incomplete regarding normal success envelope details and explicit routing to v2 alternatives, but these are minor gaps given the schema and sibling 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 description coverage is 100%, so the baseline is 3. The description adds no additional parameter-level semantics beyond the schema, but the schema itself already documents every parameter including aliases and the important deliver_to field. This meets the minimum viable standard.

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: find the cheapest price for a product query and return schema.org/Product entities with AggregateOffer data. It also adds the 'across all merchants' scope. However, it does not distinguish itself from sibling tools like find_best_price_v2 or compare_products, so it earns a 4 rather than a 5.

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 trigger conditions ('Use this whenever a user asks about prices, wants to find the cheapest option...'), which is strong usage guidance. It does not, however, explain when not to use this tool or which sibling alternatives should be selected instead, so there is room for improvement.

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 provided, the description carries the full burden and does well by disclosing the return format (schema.org/Product with AggregateOffer fields) and the shopping_job_id session mechanism. It does not discuss potential side effects, rate limits, or authentication, but for a price-lookup tool the behavioral context is reasonably complete.

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 front-loaded with the required parameter and usage triggers, and each sentence adds useful information. It is slightly repetitive around deliver_to, but overall it is well-organized and reasonably concise for the amount of context it provides.

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 absence of an output schema, the description does a good job explaining the response structure (Product entities, AggregateOffer, shopping_job_id). It could be more complete by explaining how to use the shopping_job_id to resume a session or specifying pagination/error behavior, but the essential calling context is present.

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 some value by emphasizing deliver_to as required and suggesting a default ('SG'), but it does not explain q vs product_name aliases or the region/country relationship beyond what the schema already 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 states a specific verb and resource: finding the best price across merchants, with explicit user-query triggers such as 'what's the best price for X' or 'where can I buy X for the lowest price'. It clearly conveys what the tool does, but it does not explicitly differentiate itself from sibling tools like find_best_price or compare_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?

The description gives explicit when-to-use guidance ('Use this whenever a user asks about prices...') and a concrete instruction to always pass deliver_to in the buyer's country. It does not mention when not to use the tool or name alternative tools for other cases.

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 provided, the description carries the behavioral transparency burden. It discloses that results are based on semantic meaning using title+description embeddings and that it returns up to 10 nearest neighbours. This is meaningful behavioral context, though it does not cover edge cases such as unknown product IDs or empty result sets.

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 and front-loaded: the core action and method appear in the first sentence. Every sentence adds useful information: return count, similarity basis, and the intended recommendation use case.

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 two-parameter tool with no output schema and no annotations, the description covers purpose, algorithm, result cap, and application context. It is not fully exhaustive about result fields or error behavior, but it is sufficient for an agent to select and invoke the tool correctly in most cases.

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 adds algorithmic context but does not clarify parameter semantics beyond what the schema already provides: product_id is the source product and limit is the number of results.

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 ('Find products similar to a given product') and names the resource and method ('using vector similarity'). This clearly distinguishes it from sibling search tools like search_products or find_best_price, which address different intents.

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 a concrete use case: 'Useful for "more like this" recommendations.' This gives clear context for when to invoke the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

With no annotations, the description carries the full burden and handles it exceptionally. It discloses a detailed degraded contract including meta.status='degraded', degraded_kind values, meta.diagnostic.timed_out_stage, and a guarantee that it never returns an unqualified empty result for timeout, auth failure, upstream exception, or circuit breaker failures.

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 front-loaded with the core purpose and organized logically: purpose, output shape, coverage/filters, then degraded behavior. The degraded-contract section is long but earns its place because there is no output schema and the failure mode is non-obvious.

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 9-parameter tool with no annotations and no output schema, the description is unusually complete: it covers return entity/properties, market coverage, filters, and the degraded failure contract. It does not mention the buyer-facing deliver_to requirement in prose, and the coverage mention of Indonesia vs. the country_code enum is slightly unclear.

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 adds value by naming the supported market coverage and filter domains (region values sea/us/eu/au and country values SG/US/VN/MY/...), going slightly beyond the schema text. It does not deepen semantics for limit, offset, min_discount, or deliver_to, but the schema already covers those.

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 states a specific verb and resource: 'Get discounted products sorted by discount percentage,' and it specifies the return entity shape (schema.org/Product with Offer properties). It is clear, but it does not explicitly differentiate this from the sibling get_deals_v2, so it stops short of full sibling distinction.

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 clear context for when to use the tool, including market coverage (Singapore, Malaysia, Indonesia, Thailand, Vietnam, US) and supported filters (currency, region, country). However, it does not explicitly state when to prefer an alternative sibling tool or provide 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?

No annotations are provided, so the description bears the full transparency burden. It does well by disclosing the sorted output behavior, the schema.org/Product return shape, the offer properties returned, and regional coverage. It does not discuss error cases, rate limits, or side effects, but the operation is clearly a read-style listing and the return shape is substantially 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 dense but every sentence earns its place: required parameter, purpose, sort order, return shape, coverage, and filters. It front-loads the most critical constraint, 'REQUIRED deliver_to', and avoids 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 tool with 8 parameters and no output schema, the description is fairly complete: it states the required parameter, return entity type, key properties, and supported markets. However, there are inconsistencies that reduce reliability, such as claiming support for Indonesia while country_code's enum has no ID, and listing region values (eu, au) without covering corresponding markets.

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 value beyond the schema by emphasizing that deliver_to is required, prescribing 'SG' or the buyer's country, and enumerating the currency, region, and country filters. It does not explain every parameter, but the schema already documents those clearly.

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 ('Get discounted products sorted by discount percentage') and resource, and adds return format and market coverage. However, it does not differentiate itself from the sibling tool get_deals, so an agent may not know why it should choose the v2 variant.

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 a concrete usage instruction ('Always pass deliver_to="SG" (or your buyer's country)') and mentions available filters, which helps the agent call it correctly. But it does not explicitly state when to use this tool versus siblings like get_deals, search_products, or find_best_price, leaving the routing decision mostly 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?

Without annotations, the description itself must convey behavior; it correctly implies a read operation and adds that the result includes full details and current price. It does not disclose error handling, authorization requirements, data freshness, or whether get_product_v2 should be used for more current data.

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?

Single sentence, front-loaded, and without filler. Every element—specific lookup, ID, full details, current price—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 one-parameter retrieval tool with no output schema and no annotations, the description is nearly sufficient: an agent that has a product UUID knows exactly what to expect. The only notable omission is guidance around alternatives such as get_product_v2, but the simplicity of the operation keeps this minor.

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 sole parameter id is fully described by the schema as a Product UUID, and the description merely refers to 'its ID' without adding new details. With 100% schema coverage, this meets the baseline but adds no extra semantic 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?

Clearly identifies a specific product lookup by ID and notes that full details and current price are included. It does not, however, distinguish itself from the closely named get_product_v2 sibling, so it misses full sibling differentiation.

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 phrase 'by its ID' implicitly tells an agent this is the tool to use once a product ID is known. There is no explicit mention of when to prefer get_product_v2 or search_products, nor any when-not-to-use 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?

With no annotations, the description carries the behavioral burden. It goes beyond a simple 'get' by disclosing the non-obvious BuyWhere click-tracker behavior for outbound_url and that the response includes a resolved URL when merchant offers exist. It does not cover errors or side effects, but the main behavioral surprises are surfaced.

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 tight, information-dense sentences. The required parameter is front-loaded, followed by the core purpose and then a key response behavior. No filler 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?

For a simple low-complexity get-by-ID tool, the description covers the essential call information: required parameters, core purpose, and the most notable response field. Gaps such as v1/v2 differentiation and error behavior are noticeable because there is no output schema or annotations, but they do not prevent a competent agent from invoking 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?

Schema description coverage is 100%, so the schema already documents both id and deliver_to. The description reinforces the deliver_to requirement with 'Always pass deliver_to=...' and an example, but adds no additional parameter meaning 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 a specific verb and resource: 'Get a specific product by its ID, including full details and current price.' It is easy to distinguish from search/compare tools, but it does not explicitly differentiate from the sibling get_product, so it falls just short of a 5.

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 usage context is implied: use when you already have a product ID and need full details/current price. The description gives strong operational guidance by insisting on deliver_to, but it never names alternatives like get_product or search_products, nor explains when v2 should be chosen over v1.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses the upsert semantics, the API key permission requirement, and the 1000-product batch limit. It does not cover failure modes, atomicity, or duplicate handling, but it provides meaningful behavioral context beyond the raw schema.

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 with no fluff. The primary action and resource are front-loaded, followed by usage guidance, access requirements, and batch limit. Every clause 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?

The description covers purpose, usage, auth, and batch size, which is adequate for basic invocation. However, there is no output schema and the description does not mention the response format, error behavior, or how the upsert identifies existing products, leaving some ambiguity for an agent.

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 source and products thoroughly. The description names source, SKU, title, price, URL, and optional metadata, but this largely repeats schema information without adding deeper meaning such as the unique key for upsert matching.

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 and resource: 'Ingest (upsert) a batch of products into the BuyWhere catalog.' It clearly states the tool adds or updates product listings, which distinguishes it from the sibling read/search/compare tools such as get_product and 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?

The description provides clear use context: 'Use this to add or update product listings from any merchant/source.' It implicitly distinguishes this write/ingest operation from the read-oriented sibling tools, though it does not name alternatives or explicitly 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 of behavioral disclosure. It communicates that the operation is a read-only list, but does not mention response shape, ordering, pagination, localization behavior, or the default SG market. This is minimal behavioral context.

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 single, well-scoped sentence with no filler or redundancy. It front-loads the key action and object, and every word contributes to understanding what the tool does.

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?

The tool is simple and the input schema is rich, but with no output schema and no annotations, the description leaves return format and default-market behavior implicit. It is adequate for basic selection but not fully self-sufficient for invoking the tool confidently.

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 fully documents all four parameters, including deprecation aliases, enum values, and the default. The description adds no parameter-specific meaning, which matches the 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 ('List') and a precise resource ('top-level product categories') scoped to the BuyWhere catalog. It is clearly distinct from the sibling product search/compare/deal tools, so an agent can recognize when this tool is relevant.

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 purpose statement implies the tool should be used when an agent needs to enumerate top-level product categories, and there is no competing category-listing sibling. However, it does not explicitly describe when to use it versus alternatives, nor does it mention the default country behavior that affects results.

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

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

With no annotations, the description carries the full burden, and it delivers extensive behavioral disclosure: the BUY-74597 degraded contract explains exact meta fields (status, emptiness_reason, degraded_kind, confidence, diagnostic.timed_out_stage), states that it never returns an unqualified empty result on timeout/auth/upstream failures, and instructs agents to branch on meta.degraded. This is unusually transparent about edge-case behavior.

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 longer than average, but it is front-loaded with the core purpose and arranges the additional content logically: required-like delivery context, return fields, market scope, compact recommendation, then the degraded contract. The degraded-contract paragraph is dense but essential for correct agent behavior, so the length is justified.

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 15 parameters, no annotations, and no output schema, the description is quite complete: it covers return fields, market coverage, the deliver_to requirement, and the non-trivial degraded-response contract while leaving parameter details to the schema. It is missing sibling differentiation versus search_products_v2 and any explicit pagination/rate-limit notes, but overall it is sufficient for correct invocation.

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 real semantic value: deliver_to's precedence and its role in preventing all-market scans, plus compact=true as the agent-optimized shape with normalized_price_usd. It does not re-explain every parameter, but the schema already covers their syntax and defaults.

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 action on a specific resource: "Search the BuyWhere product catalog by keyword." It also describes the return payload (product records with title, description, image, price, merchant) and the geographic scope, so an agent can clearly distinguish this from siblings like compare_products or find_similar.

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 strong usage context: deliver_to is "REQUIRED for buyer-facing use," takes precedence over country_code/country, and prevents all-market scans; compact=true is recommended for agent use. However, it never names alternatives like search_products_v2 or states when not to use this tool, so it stops short of explicit exclusion/alternative 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?

With no annotations, the description carries the behavioral burden. It discloses the required deliver_to behavior, its precedence over country_code/country, the all-market scan prevention, regional coverage, and compact-mode output differences. These are meaningful behavioral details beyond the schema. It does not discuss pagination, rate limits, or failure modes, but those are partially visible in the schema.

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 front-loaded with the most important requirement ('REQUIRED deliver_to') and is generally efficient. There is some redundancy in stating deliver_to is required three times, but each mention adds a slightly different nuance (requirement, precedence, and 'always pass'). Overall it earns its 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?

For a 14-parameter tool with no output schema or annotations, the description covers the key invocation requirement, return shape, regional scope, and agent-optimized mode. It does not explicitly address how this v2 differs from search_products or related comparison tools, which is a notable completeness gap given the sibling list.

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 adds value by explaining deliver_to's precedence and why it is mandatory, and by clarifying what compact=true returns (structured_specs, comparison_attributes, normalized_price_usd). This goes beyond the raw schema descriptions for those parameters.

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 action ('Search the BuyWhere product catalog by keyword') and the resource, with specific deliverable fields listed. However, it does not differentiate from the sibling tool search_products, so an agent cannot easily tell when this v2 is the right choice over the base version.

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 operational guidance: deliver_to is required, takes precedence, prevents all-market scans, and 'Always pass deliver_to='SG' (or your buyer's country)' is a direct instruction. It also recommends compact=true for agent use. It does not explicitly state when to prefer this tool over alternatives like search_products, so it stops short of full exclusion guidance.

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