commerce

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

Annotations declare readOnlyHint and idempotentHint, so safety is covered. The description adds that it returns offers plus lowest/highest and that links go to the LMK product page, which is helpful 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 sentence of 18 words, front-loading the purpose and efficiently stating the return content. No wasted words.

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 simple input (one parameter) and presence of an output schema (not shown), the description covers purpose and basic return structure. It lacks error handling or edge case info, but is sufficient for a tool of this complexity.

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 only parameter 'idOrSlug' has no description in the schema (0% coverage). The description does not explain its format or how to obtain it; the parameter name is somewhat self-explanatory but the description should provide more detail.

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 ('compare') and resource ('product's price across merchants'). It clearly distinguishes from sibling tools like 'get_product' or 'get_price_history' by focusing on multi-merchant comparison.

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?

No explicit guidance on when to use this tool versus alternatives. The usage is implied by the name and description, but no 'when-not-to-use' or alternative tool references are provided.

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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds useful behavioral context: 'Returns citable text with price, savings, 90-day price history, and buying options', describing the response content. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, first states purpose and usage context, second describes return values. No unnecessary words, well-front-loaded.

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 simple tool (1 parameter, output schema exists), the description fully covers what the tool does, when to use it, and what it returns. No gaps.

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% with parameter 'id' already described as 'Product id or slug from a search result'. The description adds no additional parameter semantics beyond the schema, so baseline 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 clearly states the verb 'Fetch', the resource 'product', and the scope 'by id (from a prior search result)'. It distinguishes from siblings like 'search' (lists) and 'compare_prices' (comparison).

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 'from a prior search result' clearly indicates when to use this tool, implying it should be called after a search. However, no explicit when-not-to-use or alternative tools 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying that the response includes 'curated products', indicating a non-obvious quality (not just any products). This enriches understanding beyond structured metadata.

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 of 12 words, no redundancy. Every word contributes essential meaning: verb, resource, scope, and identifier method. Ideal length for a straightforward retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values do not need elaboration. However, the description lacks details on error behavior (e.g., 404 if slug not found), case sensitivity, or pagination implications of the 'limit' parameter. Complexity is low, so this is a minor gap, but enough to prevent a 4.

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 0% for 2 parameters. The description only mentions 'slug' with no explanation of its format or constraints, and completely omits the 'limit' parameter. The baseline of 3 is not justified because the description fails to compensate for the schema's lack of descriptions, leaving the agent uninformed about parameter roles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the specific action ('Get'), the resource ('single editorial collection and its curated products'), and the identifier ('by slug'). This distinguishes it from sibling tools like list_collections (which lists multiple) and get_product (which retrieves a single product without related collection context).

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?

No explicit guidance on when to use this tool versus alternatives like list_collections or search. The description implies usage when you have a specific slug, but fails to mention that for browsing or filtering, other tools are more appropriate. Context is implied but not articulated.

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 idempotentHint, so the description adds value by explaining the ranking logic and time-bounded nature (today's deals), but does not disclose pagination or error handling.

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 efficient sentences front-load the core purpose and key filters, with no redundant or irrelevant information.

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, scoring criteria, and main filters. Since an output schema exists, return value documentation is covered. Missing details like default limit behavior or pagination, but adequate for typical use.

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 0%, but the description explains two of three parameters (category and minDiscountPercent) with meaningful usage context. The 'limit' parameter is not mentioned, but the coverage is above what the schema alone 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?

Description clearly states the tool retrieves 'Today's best deals' with specific ranking criteria (LMK's deal-quality scoring). It distinguishes itself from siblings like get_product or get_price_history by focusing on deals and their quality ranking.

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?

Description mentions optional filters but does not provide explicit guidance on when to use this tool versus alternatives. No context about prerequisites or exclusions is given, though the tool is clearly for deal discovery.

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 provide readOnlyHint, openWorldHint, etc. Description adds valuable context about blending curated search with demand signals, going beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, no redundancy. Front-loaded with key purpose and method.

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?

Output schema exists, but description does not explain return structure. Lacks details on default behavior for optional parameters or how blending is performed. Adequate but not 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 only 25% (only query has a description). Description mentions budget and recipient/occasion but does not explain or add meaning to individual parameters like limit, minPrice, or maxPrice.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states action (gift recommendations), resource (ideas), and context (recipient/occasion within budget). Differentiates from siblings like search and get_product by being gift-specific.

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?

Implied usage for gift recommendations, but no explicit when to use vs. alternatives like search_catalog or get_trending_products. No exclusions or prerequisites 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context that results are 'aggregate counts only' over a 180-day window, which clarifies the scope and limitations. No contradictions found.

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 very concise at two sentences, with front-loaded key information (most-wishlisted, 180-day, aggregate). However, the second sentence ('Unique LMK demand data') adds limited value and could be merged or expanded.

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 output schema exists, the description adequately conveys what the tool returns. However, parameter semantics are entirely missing, which is critical for correct invocation. The tool has 3 optional parameters with no description, making it incomplete for an agent to use properly.

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 has zero description coverage for parameters (limit, maxPrice, minPrice). The description does not mention any parameters, leaving the agent to infer their purpose from names alone. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool returns 'most-wishlisted products' based on a 180-day demand signal from LMK lists, with aggregate counts only. The name itself includes 'get' and the description distinguishes it from sibling tools like get_trending_products by emphasizing 'Unique LMK demand data.'

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 implies usage for retrieving wishlist-based demand data but does not provide explicit guidance on when to use this tool versus alternatives such as get_trending_products or get_deals. No when-not-to-use or prerequisite information is given.

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 idempotentHint=true, so the description adds value by mentioning 'LMK-proprietary price intelligence' and the default 90-day window. However, it does not detail other behavioral aspects like response format or pagination, which are partially covered by the output 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 extremely concise with two sentences, front-loading the core purpose and adding a key differentiator (proprietary data) without any waste.

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 low schema coverage (0%) and presence of an output schema, the description is incomplete. It lacks parameter explanations and usage context, which are critical for an agent to invoke the tool correctly. The output schema exists but does not compensate for missing parameter semantics.

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 0%, so the description should compensate. It only hints at 'daysBack' by mentioning a default 90 days but does not explain either parameter (e.g., what idOrSlug represents). This adds minimal value beyond the schema's type and constraints.

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 verb 'get' and the resource 'price history and stats for a product', which distinguishes it from sibling tools like get_product or compare_prices. The mention of 'LMK-proprietary price intelligence' further differentiates the tool's unique data source.

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 does not provide any guidance on when to use this tool versus alternatives. It only implies a trailing window default of 90 days but lacks explicit conditions, exclusions, or references to sibling tools.

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 no destructive effects. The description adds value by detailing the response structure (enriched card, price stats, cross-merchant options), which provides behavioral context beyond the annotations. It does not disclose additional behaviors like rate limits or auth, but the combination 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 a single sentence that immediately states the main purpose and key returns (enriched card, price stats, buying options). No unnecessary words, front-loaded effectively.

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 presence of an output schema (and thus no need to detail return values), the description covers the essential scope: fetching a single product with detailed info. It lacks mentions of error handling or parameter formatting but is otherwise complete for a simple 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 for the single parameter, the schema already fully describes 'idOrSlug' as 'Product slug, id, or external id'. The description does not add any further semantic meaning for the parameter, so baseline 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 clearly states it gets a single product with full detail, including enriched card, 90-day price stats, and cross-merchant buying options. It distinguishes from siblings like get_price_history (which focuses on price history alone) and get_popular_products (which returns multiple 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 implies when to use this tool (when you need full product detail for one product), but does not explicitly state when not to use it or mention alternatives among the sibling tools. No direct guidance on selection criteria beyond the inferred scope.

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 indicate read-only, idempotent, non-destructive behavior. Description adds that results are aggregate counts only and limited to the last 30 days, which is useful behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with key information, every word adds value. Efficient and clear.

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 tool with one optional parameter, an output schema, and comprehensive annotations, the description adds the missing time-window and aggregation context. No further information is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no descriptions for parameters). The single 'limit' parameter is not mentioned in the description; no additional meaning is provided beyond the schema type and constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool retrieves products gaining momentum based on wishlist additions in the last 30 days. It distinguishes from sibling 'get_popular_products' by specifying the metric (wishlist adds) and time window.

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 implies use when trending products by wishlist counts are needed, but does not explicitly state when not to use or mention alternatives. The clear context is sufficient for general guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds limited behavioral context by specifying 'published editorial collections'. It does not disclose additional behaviors like ordering or pagination.

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?

A single sentence of 13 words that front-loads the core purpose. Every word is meaningful, with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and annotations cover safety, the description provides sufficient context for a simple list tool. It mentions the scope ('published editorial collections') but could hint at pagination or the limit parameter.

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 0% schema description coverage and one parameter (limit), the description does not explain the parameter's meaning or usage. The parameter name and constraints are self-evident but the description adds no value beyond inference.

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 lists 'LMK's published editorial collections' and provides examples like occasions, holidays, beauty, style, sports. This specifies the verb (list) and resource (editorial collections), and the examples differentiate it from sibling tools like get_collection or search.

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 implies usage by listing categories but does not explicitly state when to use this tool over alternatives like get_collection (which likely retrieves a single collection) or search. No guidance on when not to use it or prerequisites.

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 idempotentHint. The description adds batch resolution context but omits behavior on partial failures, error handling, or return structure. Acceptable given annotations cover safety, but more detail would help.

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, zero wasted words, front-loaded with key action and resource. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and single parameter, the description covers the basic purpose and ID types. Missing details like batch size (max 50, in schema), error behavior, and return format explanation. Adequate for a simple tool but not thorough.

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 0%, so description must compensate. It explains the ids parameter accepts LMK slug, id, or external/merchant IDs, adding meaning. However, no format examples or constraints are provided, which limits 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?

The description clearly states the tool batch-resolves products by specific identifiers (LMK slug, ID, external/merchant ID). It distinguishes from siblings like get_product (single) and search_catalog (search), making it 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?

No guidance on when to use this tool versus alternatives. With 11 sibling tools (e.g., get_product for single lookups, search_catalog for searching), the description should explicitly mention preferred use cases or 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?

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that results are citable and include product-page URLs, which is useful behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two informative sentences. Front-loaded with action and key information. Could be slightly more concise but effectively communicates purpose and alternatives.

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 simplicity (2 params, no nested objects, output schema present), the description covers purpose, output format, and distinctions from siblings. Minor omission: no mention of default limit or pagination.

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 50% (only 'query' described). The description does not add meaning for the 'limit' parameter, and 'query' is already described in the schema. No additional parameter semantics provided.

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 searches LMK products and returns citable results with canonical URLs. It also distinguishes itself from search_catalog by noting that search_catalog is for price/brand/on-sale filters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides usage guidance: 'Use for shopping/discovery.' and directs to search_catalog for filter-based queries. This helps an agent decide when to use this tool versus 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 (readOnlyHint, idempotentHint, openWorldHint) already establish safety and idempotency. The description adds value by specifying the return type (products with LMK links), which is beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences, front-loaded with the core action, and every word adds value. No redundancy.

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?

While the description is clear for basic usage, the tool has 6 parameters (only query described), and output schema exists but is not referenced. The description does not mention filtering or sorting capabilities, leaving gaps for a search tool. Adequate but not thorough.

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 only 17% (only query has description). The description does not elaborate on brand, limit, onSale, maxPrice, or minPrice, leaving the agent without guidance on these parameters. With low coverage, the description should compensate but fails to do so.

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: searching a curated cross-merchant catalog and returning products with links. The phrase 'Use for "find me X" shopping queries' effectively distinguishes it from sibling tools like compare_prices or get_product, meeting the highest standard.

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 indicates when to use the tool ('find me X' shopping queries), providing clear context. However, it does not mention when not to use it or explicitly exclude alternatives, missing the top score of 5.

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