commerce

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

Annotations already mark it as read-only and idempotent. The description adds value by detailing the return structure (offers, lowest/highest, links to LMK product page) without contradicting 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?

The description is a single sentence with no wasted words, efficiently conveying the tool's purpose and key output details.

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 an output schema, the description is mostly complete but lacks parameter explanation, which is a notable gap given the parameter's importance.

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, the description must compensate. It does not explain the single parameter 'idOrSlug', leaving the agent to infer its purpose from the name alone.

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 compares a product's price across merchants, with specific outputs (offers, lowest/highest, links). This distinguishes it from sibling tools like get_product or get_price_history.

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 current price comparisons but does not explicitly state when to use this tool over alternatives or provide 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and description adds useful output specifics (citable text with price, savings, 90-day price history, buying options).

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, no wasted words, information front-loaded 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, description covers purpose, usage context, and output sufficiently. Complexity is low and no gaps are apparent.

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 100% description coverage for the single parameter 'id'. Description adds minor emphasis on 'from a prior search result' but does not add substantial meaning beyond 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?

Description clearly states verb (fetch), resource (product detail by id), and distinguishes from siblings by specifying it retrieves full detail for one product from a prior search result.

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 indicates usage context (from a prior search result) but does not explicitly state when not to use or name alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating a safe, read-only operation. The description adds context by stating the tool returns 'curated products' and retrieves a single collection, which goes beyond the annotations. However, it does not discuss any potential error conditions or further behavioral details.

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 10 words, which is concise. However, it sacrifices important detail by not documenting the limit parameter, making it somewhat incomplete. It is front-loaded with the key action but lacks necessary specificity.

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 parameters, no nested objects) and the presence of an output schema (though not shown), the description provides the core purpose but fails to address the limit parameter. With sibling tools providing context, it is marginally adequate but could be more 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?

The input schema has 2 parameters (slug and limit) with 0% schema description coverage. The description only mentions 'by slug' and completely omits the limit parameter, which controls the number of products returned. For a tool with no property descriptions, this is insufficient.

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 the verb 'Get' and specifies the resource 'editorial collection and its curated products' with the parameter 'by slug', making it clear what the tool does. It distinguishes from sibling tools like list_collections (which lists multiple collections) and search_catalog (which is for searching).

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 when you have a slug for a specific editorial collection, but it does not provide explicit guidance on when to use this tool over alternatives like list_collections or search_catalog. No when-not-to or exclusions are stated.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable context about the internal scoring mechanism (discount depth, price sweet spot, merchant quality) and filtering options, which goes 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?

Single sentence with no wasted words. Front-loaded with the core purpose ('Today's best deals, ranked...') and then optional filters. Highly concise.

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

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

Given the presence of an output schema (not shown), the description appropriately focuses on input and behavior. It explains scoring logic, filters, and ranking. No obvious gaps for a deals listing tool.

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

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

Schema description coverage is 0%, but the description clarifies that 'category' is a slug and 'minDiscountPercent' is a minimum discount percentage. It does not explain the 'limit' parameter or default behavior, so it partially compensates for the lack of schema descriptions.

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

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

Description clearly states the tool returns today's best deals ranked by LMK's proprietary deal-quality scoring, with optional filters by category or discount. This distinguishes it from sibling tools like search, get_product, or get_trending_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 implicitly tells when to use (to get top deals) and lists optional filters, but it does not explicitly state when not to use this tool or compare it to alternatives like search or get_gift_ideas.

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 readOnlyHint, idempotentHint, and not destructive. The description adds behavioral context by stating it 'blends curated search with LMK demand signals', which explains how results are generated. No contradictions 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?

The description is two sentences long, with the first sentence stating the core purpose and the second adding behavioral nuance. No unnecessary words, 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 presence of annotations (readOnly, idempotent), an output schema, and a moderate number of parameters, the description covers the essential purpose, input hints, and behavioral traits. It lacks details on pagination or result handling, but those are partially covered by the schema and annotations.

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). The description hints that 'query' is for recipient/occasion and that minPrice/maxPrice relate to budget, but it does not detail format, constraints, or the 'limit' parameter. Given the low coverage, the description adds some value but not enough to fully compensate.

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 provides gift recommendations for a recipient/occasion within a budget. It mentions blending curated search with LMK demand signals, which differentiates it from general search tools like 'search' and 'get_popular_products'. However, it does not explicitly list sibling tools or contrast them.

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 this tool (gift recommendations for a specific recipient/occasion and budget). It does not provide explicit when-not-to-use guidance or alternatives, but the context is sufficient for an agent to decide.

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, idempotent, non-destructive. The description adds context about the 180-day window, aggregate-only counts, and source (LMK lists), providing value 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 sentences, front-loaded with the key result and time window. No fluff. Could benefit from slightly more structured formatting but is efficient.

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, the description adequately covers source, time window, and aggregate nature. However, it lacks explanation of optional parameters and ordering/pagination, which are relevant contextual details.

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%, meaning the description provides no information about parameters (limit, minPrice, maxPrice). The agent must rely solely on the schema property names and constraints, which is insufficient for optimal use.

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 returns 'most-wishlisted products' with a 180-day demand signal, which is specific and distinguishable from siblings like 'get_trending_products'. The phrase 'aggregate counts only' further clarifies the scope.

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 for wishlist-based popularity over 180 days, but does not explicitly state when not to use or mention alternatives. With sibling tools listed, the agent may infer, but explicit guidance is missing.

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=true, idempotentHint=true, destructiveHint=false) already disclose the safe, read-only nature. The description adds 'LMK-proprietary price intelligence' and specifies the trailing window, but does not elaborate on data freshness, caching, or accuracy beyond what annotations provide.

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

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

The description is concise (two sentences) and front-loaded with the verb 'Get'. However, it could be more structured by listing parameters or usage context. 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?

Although an output schema exists (reducing the need to describe returns), the description lacks parameter documentation and does not mention the required idOrSlug field. For a tool with 2 parameters (one required), this is incomplete.

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%—the description does not explain any parameters. The only parameter hint is 'default 90 days' for daysBack. idOrSlug is completely undocumented in the description. With low coverage, the description should compensate but largely 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 'Get price history and stats' with a specific resource (product) and scope (trailing window, default 90 days). It distinguishes itself from sibling tools like 'get_product' and 'compare_prices' by focusing on historical price 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 historical price data with a default window of 90 days, but it does not explicitly state when to use this tool versus alternatives like 'get_product' or 'compare_prices'. No when-not-to-use guidance is 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 declare readOnly and idempotent behavior. The description adds value by specifying the output's rich structure (price stats, buying options), which annotations do not cover. 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?

A single, front-loaded sentence delivers the core functionality and key output features with zero extraneous 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 single-parameter schema and presence of an output schema, the description fully summarizes what the agent can expect (enriched card, price stats, buying options), making it complete for decision-making.

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 a clear description for idOrSlug ('Product slug, id, or external id'). The description does not add additional meaning beyond what the schema already provides, achieving the baseline.

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

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

The description clearly states the tool retrieves a single product with comprehensive detail, including enriched card, 90-day price stats, and cross-merchant options. This verb+resource combination uniquely identifies its purpose among siblings like get_price_history and compare_prices.

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 needing full product detail for one item, but does not explicitly differentiate from alternative tools or provide when-not-to-use guidance. No exclusions or sibling comparisons are 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 destructiveHint=false, so the description adds value by specifying that it returns only aggregate counts and covers a 30-day window. This contextualizes the tool's behavior beyond the structured 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?

The description is a single concise sentence that front-loads the core purpose ('Products gaining momentum') and includes key modifiers. Every word is necessary with 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?

Given the existence of an output schema (not shown), the description need not detail return values. For a simple read-only list tool with one optional parameter, the description covers the data source and aggregation. However, not mentioning the limit parameter slightly reduces completeness.

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 (limit) has 0% schema description coverage, meaning the schema provides just type and constraints. The tool description does not mention the limit parameter at all, so it fails to add meaning. The agent must infer its purpose from the name and context, which is insufficient.

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 returns products gaining momentum based on wishlist adds in the last 30 days, with aggregate counts only. The verb 'get' and resource 'trending products' are specific, and it naturally distinguishes from siblings like get_popular_products by specifying the metric 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 when to use (for trending products based on wishlist activity) but provides no explicit guidance on when not to use or how it differs from alternatives like get_popular_products, get_deals, or search. Usage context is implied but lacks exclusions or comparisons.

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, destructiveHint=false. The description adds that collections are 'published' and provides categories, but no further behavioral traits beyond what annotations cover.

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, front-loaded sentence with no wasted words. Every part 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?

Output schema exists, so return values are covered. The description is adequate for listing collections but lacks explanation of the optional limit parameter. Minor gap.

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 single parameter 'limit' is not mentioned in the description. Schema provides min/max but not semantics. With 0% schema coverage, the description should explain the parameter but does not.

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 published editorial collections, providing specific examples (occasions, holidays, beauty, style, sports) that differentiate it from siblings like get_collection (single) and search_catalog (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?

Usage is implied by the description and list of siblings (e.g., get_collection for specific, search for broad search), but no explicit when-to-use or when-not-to-use guidance 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, idempotentHint=true, destructiveHint=false, establishing a safe read operation. Description adds value by specifying batch resolution (up to 50 items) and multiple ID types, which annotations do not cover. 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?

Single sentence with no redundancy. Every word is informative: verb, resource, key types. Front-loaded and efficient.

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, description need not explain return values. It covers purpose and input keys. For a batch lookup tool with known identifier types, this is largely complete, though absence of usage context slightly limits completeness.

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?

Input schema has 0% coverage (no descriptions on parameters). Description partially compensates by explaining that the 'ids' array contains LMK slugs, product IDs, or external/merchant IDs, but does not provide format details or examples. Adequate but could be richer.

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 uses specific verb 'Batch-resolve', identifies resource 'products', and lists three distinct identifier types (LMK slug, id, external/merchant id). This clearly differentiates from sibling tools like get_product (single product) and search_catalog (query-based 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?

Description implies usage when you have LMK slugs, product IDs, or external/merchant IDs, but does not explicitly state when not to use it or compare with alternatives like get_product for single lookups. Guidance is implicit rather than explicit.

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, and destructiveHint, but the description adds valuable behavioral context about return format (citable results with canonical URLs) and the shopping/discovery use case, without contradicting 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, no filler, front-loads purpose and immediately directs to alternative when appropriate, earning every sentence.

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 search tool with output schema, the description covers purpose, usage, and result characteristics. It omits pagination or limit details but overall is sufficient given the output schema likely documents return structure.

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 adds no extra parameter semantics beyond the schema, leaving the 'limit' parameter unexplained. With only moderate coverage, the description should have provided more guidance.

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, and explicitly distinguishes it from search_catalog for filtering tasks, demonstrating specific verb+resource and 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?

Directly advises 'Use for shopping/discovery' and explicitly states when not to use it ('For price/brand/on-sale filters, use search_catalog'), providing clear usage context and alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds a bit more context (curated catalog, product-page links) but does not disclose other behaviors like rate limits 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?

Two sentences, no wasted words. The description is front-loaded with the core purpose and usage hint.

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 has 6 parameters and siblings, the description covers the core purpose but lacks details on filtering parameters. Output schema exists so return format is covered, but usage parameter guidance is missing.

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

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

Schema description coverage is only 17% (only 'query' described). The description does not explain the other five parameters (brand, limit, onSale, maxPrice, minPrice), failing to compensate for the low coverage.

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's curated cross-merchant catalog and returns products with product-page links, distinguishing it from siblings like 'search' and 'get_product' by specifying cross-merchant scope.

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

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

It explicitly says 'Use for "find me X" shopping queries', which gives a clear usage context. It does not mention when not to use it or alternatives, but the guidance is direct and helpful.

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