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 provided, the description carries the full burden and does so unusually well. It documents the exact degraded 200-OK contract, including meta.status, emptiness_reason, degraded_kind, confidence, and diagnostic.timed_out_stage, and explicitly instructs callers to branch on meta.degraded or meta.status. It also states a strong guarantee: it never returns an unqualified empty result for timeout, auth failure, upstream exception, or circuit breaker.

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 tool has many behavioral edge cases, so the length is justified. The main action and return shape are front-loaded, and the degraded contract is clearly marked as a named section (BUY-74597). Some verbosity remains in ticket IDs and repeated meta fields, but each 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?

For a 10-parameter tool with no output schema and no annotations, the description supplies return shape, geographic scope, filter set, and a full failure-handling contract. One minor ambiguity is that Indonesia is named as covered while the country_code enum omits ID, and pagination limits are only visible in the schema. Overall, it is nearly complete for invocation purposes.

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 high-level filter support and geographic scope, but it does not materially explain per-parameter semantics such as the importance of deliver_to, pagination via offset, or min_discount behavior; those are already covered by the schema. This is adequate but not additive.

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 first sentence is precise: 'Get discounted products sorted by discount percentage' names the verb, resource, and ordering behavior. It also describes the return entity shape, leaving little doubt about what the tool does. However, it does not explicitly differentiate itself from sibling tools like get_deals_v2 or search_products, so it misses the top tier.

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 explains supported filters and how to interpret degraded responses, but it gives no guidance on when to choose this tool over get_deals_v2 or search_products. It also does not state the deliver_to requirement for buyer-facing shipping ranking beyond what the schema already says. There is no explicit when-to-use or 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 full burden of behavioral disclosure. It does disclose the return format (schema.org/Product with Offer properties) and the covered markets, and 'Get' implicitly indicates a read operation. However, it does not explicitly state that the operation is non-destructive, nor mention sorting direction (ascending/descending) for discount percentage, pagination behavior, or how invalid/missing deliver_to is handled. This is adequate but not thorough.

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 reasonably sized but contains redundancy: 'REQUIRED deliver_to' and 'Always pass deliver_to="SG"' convey the same message twice. The list of supported countries appears twice in slightly different forms (first as prose, then in the filter enumeration). It is front-loaded with the required parameter and purpose, but the redundant phrasing weakens overall conciseness.

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 9 parameters, no output schema, and no annotations, the description provides a decent overview but leaves gaps. It explains return type and filters, but does not clarify the relationship between region and country, the exact sorting order, or how pagination (limit/offset) behaves. The inconsistency about Indonesia vs. the enum also adds ambiguity. It is sufficient for basic invocation but not fully comprehensive for all edge 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 description coverage is 100%, so the baseline is 3. The description adds a bit of guidance on deliver_to ('Always pass deliver_to="SG"...'), and it restates the filter dimensions (currency, region, country, category) but does not deepen understanding beyond the schema. The mention of coverage includes Indonesia, which is not present in the country_code enum, creating slight ambiguity rather than clarifying parameter semantics.

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 function: 'Get discounted products sorted by discount percentage.' It identifies a specific verb and resource, and adds scope by listing covered regions. However, it does not explicitly differentiate itself from the sibling tool 'get_deals' (v1), relying on the version suffix rather than naming what makes v2 distinct.

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 only usage guidance is 'Always pass deliver_to="SG" (or your buyer's country),' which is really a parameter requirement rather than guidance on when to choose this tool over alternatives. It does not mention any when-not-to-use conditions, exclusions, or compared search_products, get_product, or find_best_price. The coverage list gives some context but no routing between 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?

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.