La Luer — AI Skincare Commerce

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

Annotations indicate readOnlyHint and destructiveHint are both false (non-destructive). The description adds behavioral specifics beyond annotations, such as displaying required consumables for devices and compatible devices for topicals, which gives the agent a clear understanding of the tool's response logic without requiring a separate annotation.

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 with the primary purpose. Every sentence provides valuable information: the core function, two behavioral modes, and concrete usage examples. There is no redundant or filler content.

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 (one parameter, no output schema), the description is complete: it explains what the tool does for both device and topical products, gives concrete examples, and implies the return value is a list of compatible products. No major gaps are 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?

The input schema already provides a complete description of the 'product' parameter (name or SKU), achieving 100% coverage. The description does not add additional parameter-specific semantics beyond the examples, so it meets the baseline for high schema 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's function: 'Check which products are compatible with a given product.' It further specifies behavior for devices and topicals, distinguishing it from sibling tools like compare_products or recommend.

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

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

Explicit usage context is provided with customer-facing example questions: 'what gel do I need with MIRA?' or 'does this serum work with CryoSculpt?' This clearly signals when to use the tool, though it does not explicitly mention when not to use it or alternative 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 destructiveHint=false, so the safety profile is known. The description adds valuable context beyond annotations by noting the tool uses the Shopify Storefront API and checks 'real-time stock status,' implying freshness of data. It does not describe return format or edge cases, but for a read-only check, the annotations plus real-time detail are sufficient.

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

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

The description is two sentences, front-loaded with the main action ('Check if a product is currently available'), and includes a concrete example customer query. Every sentence earns its place: purpose, implementation detail, and usage guidance without filler.

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

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

This is a simple tool with one well-documented parameter, strong annotations, and no output schema. The description covers the core purpose and real-time nature, and the phrase 'check if available' implicitly signals a boolean-like result. Missing details like behavior for unknown products are minor, so the description is sufficiently complete for 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?

Schema coverage is 100%: the single parameter 'product' is described as 'Product name or SKU to check availability for.' The description adds no additional meaning beyond the schema (it only restates 'product'), so the baseline 3 applies without any enhancement.

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 with a specific verb and resource: 'Check if a product is currently available.' It further narrows scope with 'real-time stock status' and includes a concrete use case ('is MIRA in stock?'). This distinguishes it from sibling tools like get_product or search_products, which focus on product details or search rather than availability.

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 explicit triggers: 'Use when a customer asks ... or before recommending a product.' This gives clear context for when to invoke the tool. However, it does not mention when not to use it or name alternative tools, so it falls short of an explicit when/when-not with 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?

The description discloses the return shape: 'Returns structured comparison with shared attributes, differences, tradeoffs, and a decision hint.' It also implies a non-destructive read operation consistent with the readOnlyHint annotation. It goes beyond the schema by outlining the analytical output.

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 compact: two sentences that front-load the core action and immediately follow with usage guidance. No filler.

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

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

For a single-parameter tool with no output schema, the description covers purpose, usage conditions, alternatives, and the nature of the output. It provides enough context for an agent to select and invoke 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?

The schema already provides a detailed description for the 'products' parameter (product titles or SKUs, minItems=2, maxItems=5). The tool description reinforces the 'two or more' requirement but does not add significant new semantics beyond the schema.

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

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

The description uses the specific verb 'compare' with the resource 'products' and specifies 'side by side', clearly distinguishing it from single product lookup by naming get_product as the alternative.

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 states when to use ('when the user asks to compare, says X vs Y, or wants to decide between options') and when not to ('Do not use for single product lookup — use get_product'), providing clear 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?

Beyond annotations (readOnlyHint=false, openWorldHint=true), the description discloses that product URLs are resolved to variant IDs automatically, that no catalog import is needed, and that decision_id may be required for authority-gated checkout. These are useful behavioral details not present in 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 concise, front-loaded with the core purpose, and each sentence adds value. It avoids repetition and stays within a few sentences.

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

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

Given no output schema and a tool with multiple input modes and a conditional requirement, the description covers all necessary aspects: how to specify products, the authority-gated checkout caveat, and the return value. It is complete for the agent to select and invoke 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 baseline is 3. The description adds meaning by explaining the 'no catalog import needed' advantage and consolidating supported features (discount codes, cart notes, selling plans), though most parameter details are already in 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 'Create a checkout URL for one or more products' with specific verbs and resources. It also distinguishes from siblings by explicitly saying not to use it unless the user wants to buy, and points to search_products or skincare_recommend as alternatives.

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 when-to-use guidance: 'Do not use unless the user wants to buy — use search_products or skincare_recommend first.' This clearly differentiates from alternatives and gives the agent a decision rule.

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 safety is covered. The description adds the behavioral instruction 'Always ask if the customer has a discount code,' which goes beyond annotations and informs the agent of a required interaction. There is no contradiction.

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

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

The description is three sentences and front-loaded with the main purpose. It is mostly concise, though 'ask about discount codes' appears in the first and third sentences, creating slight redundancy. The third sentence adds the 'always' emphasis, so it is not a major flaw.

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 with one optional parameter and no output schema. The description explains when to use it and what it does, covering the essential aspects. It does not specify the return format, but for a show-deals tool that is acceptable given the low complexity 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?

The schema has one optional parameter with a description covering its meaning. The description mentions discount codes but does not add significant detail beyond the schema. Since schema coverage is 100%, the baseline 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 clearly states 'Show available bundles, deals, and ask about discount codes,' which is a specific verb+resource. It distinguishes itself from sibling tools like recommend and shop by focusing on deals/discounts.

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 lists when to use the tool: 'when a customer asks about deals, bundles, savings, or says do you have any discounts?' and 'when multiple items are in cart to suggest bundle savings.' However, it does not mention when not to use it or alternative tools, so it lacks full 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, destructiveHint=false, so the safety profile is covered. The description adds useful return format context ('Returns a widget card with the product details, image, price, and checkout button'), going beyond annotations. It does not mention edge behaviors like both params provided, but this is a minor gap given the read-only nature.

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?

Three sentences: the first states the tool's purpose, the second gives usage guidelines with examples, the third explains the return value. Every sentence contributes unique value, and the description is front-loaded with the core function. No redundancy or 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?

The tool is simple (2 optional params, no output schema). The schema documents parameters, annotations cover safety, and the description covers purpose, usage, return format, and exclusions. There is no missing information that an agent would need to invoke 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%: 'sku' is described as 'Exact product SKU (e.g. ...)' and 'title' as 'Product title to search for (fuzzy match)'. The description merely echoes 'by SKU or title' without adding new parameter-level meaning. Since the schema already fully explains the parameters, a 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 starts with 'Get full details for a specific product by SKU or title,' which names the exact verb and resource. It distinguishes itself from sibling tools by explicitly saying 'Do not use for browsing or recommendations — use search_products or skincare_recommend.' This makes the tool's scope clear and unique.

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 provides explicit when-to-use guidance ('when the user asks about a specific product by name') with concrete query examples. It also includes when-not-to-use instructions and names the exact alternative tools, giving the agent clear decision criteria.

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 the description adds that the output consists of the summary and URL. This provides a clear expectation of the tool's behavior without contradicting 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?

The description is a single, front-loaded sentence that conveys all necessary information without any wasted words. It is appropriately sized for the tool's simplicity.

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, read-only tool with no output schema, the description sufficiently covers the return type (summary and URL), the parameter's origin, and the tool's purpose. No additional context is needed 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?

The schema fully describes the 'slug' parameter with an example, and the description adds the practical context that the slug comes from search_research_notes. This helps the agent understand how to obtain a valid value, exceeding baseline schema 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 retrieves a specific SearchShopAI Research Note's summary and URL by slug. It distinguishes itself from sibling tool search_research_notes by explicitly mentioning the slug is returned by that search function.

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 the tool should be used after search_research_notes, as it references the slug being returned by that tool. This gives clear context for when to use it, though it does not explicitly list exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context by describing the return payload: scored products with checkout URLs, safety assessment, and authority state (SHOULD/CAN/SHOULDNT/ESCALATE/CANT). This goes beyond the annotations and informs the agent about its transactional authority level, which is crucial for deciding next steps.

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

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

The description is two sentences, front-loaded with the core purpose and ending with usage guidance and return format. Every sentence delivers distinct value without redundancy or unnecessary detail.

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 moderate complexity and no output schema, the description adequately explains return values (scored products, checkout URLs, safety assessment, authority state). It covers the main user-facing outcomes. It does not mention error cases or behavior for invalid inputs, but with full schema coverage and clear return format, it is sufficiently complete for an AI agent to invoke 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 baseline is 3. The description does not add specific parameter semantics beyond what the schema already provides (e.g., query is a natural language description, brand filters, domain auto-detection). It mentions domain-expert scoring but does not elaborate on parameter usage, so the schema remains the primary source of parameter meaning.

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: 'Get a personalized product recommendation' with domain-expert scoring and safety notes. It also specifies the return types (scored products, checkout URLs, safety assessment, authority state). However, it does not explicitly distinguish itself from sibling tools like 'skincare_recommend', which appears to be a specialized variant, so it lacks 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 description provides explicit when-to-use guidance: 'Use when the user wants advice, has a concern, or asks what to buy.' It does not mention alternatives or exclusions, but the context is clear and sufficient for typical recommendation queries.

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. Description adds behavioral specificity by stating it returns all matching products with prices, images, and checkout, and clarifies it does not score/filter unlike skincare_recommend, providing context 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?

Three sentences, front-loaded with purpose, use cases, and explicit alternative. Every sentence contributes meaning without redundancy or filler.

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

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

Description covers return format, use cases, and alternative tools; schema covers all parameter details. Lacks explicit handling of edge cases like zero results or pagination, but max_results parameter and overall simplicity make it adequate.

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 100% description coverage with detailed explanations for all four parameters (e.g., category warns against guessing, max_results explains default). The description adds no new parameter-specific semantics beyond mentioning 'browse by category', so performance is at 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?

Description states 'Browse and search the product catalog' with specific verbs and resource, and explicitly contrasts itself with skincare_recommend, distinguishing it from sibling tools. It also lists concrete use cases like 'show me' and 'what do you have'.

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 when-to-use scenarios and an explicit exclusion: 'Do not use when the user needs personalized recommendations... use skincare_recommend instead.' This clearly guides selection against the most similar sibling tool.

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 safety profile is known. The description adds that the tool returns 'matching articles with titles, summaries, and URLs,' which is a return-format detail but not deeper behavioral context. With annotations covering the key aspects, this is adequate but not rich.

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

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

The description is two sentences, front-loaded with the main action and scope. Every sentence earns its place: one defines the tool's function and content, the other gives usage guidance. 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?

For a simple read-only search tool with one parameter and no output schema, the description fully covers what it does, what it returns, and when to use it. Combined with the annotations, the agent has all needed information to correctly select and invoke it.

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%; the parameter 'query' is well-defined with examples ('attribution', 'MCP', 'hallucinated prices'). The description's mention of blog topics adds some semantic context but does not significantly exceed 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 starts with a specific verb and resource: 'Search SearchShopAI's Research Notes blog' and clearly distinguishes it from product search or note retrieval. It also names the content domains (agentic commerce, AI attribution, MCP, etc.), making the tool's purpose unambiguous.

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

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

The description includes an explicit usage directive: 'Use when asked what SearchShopAI has written or published about a topic.' This clearly indicates when to use the tool, though it does not explicitly contrast with siblings like get_research_note or search_products.

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, covering the safety profile. The description adds transparency about its routing/natural-language-understanding behavior and emphasizes lossless preservation of qualifiers. It does not mention return format, but this is less critical given the safety annotations and no 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 four sentences, front-loaded with 'Start here', and every sentence provides actionable value. It avoids redundancy and is appropriately sized for a router tool's complexity.

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 one required parameter and no output schema, the description adequately covers input requirements, capabilities, and alternative tools. It does not enumerate all possible intents (e.g., 'buy', 'question') but the 'any shopping request' phrasing is inclusive. Slight gap on return behavior is acceptable without an output schema.

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

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

Schema coverage is 100% with descriptions for each parameter, so baseline is 3. The description adds significant meaning by stressing that `request` is the primary signal and all other parameters are 'secondary hints only', which is partially in the schema but reinforced through the instruction to pass the complete request verbatim. This clarifies how to prioritize inputs.

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 role: 'Start here for any shopping request' and explains it routes to capabilities like personalized recommendation, catalog search, product lookup, or comparison. It distinguishes itself from the granular sibling tools by naming them explicitly as precise follow-ups.

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: 'Prefer this tool whenever the request is conversational or carries any nuance.' It also states that granular tools (search_products, get_product, compare_products, create_checkout) remain available for precise follow-ups, providing clear exclusions 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 indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it returns a widget with cart items and a working checkout link, clarifying the output and emphasizing 'real' checkout behavior. It doesn't contradict annotations but could provide more detail on side effects like cart persistence.

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

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

The description is three sentences: purpose, modes, and usage boundary. Every sentence adds distinct information with no fluff, making it easy to scan.

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 three optional parameters and no output schema, the description adequately covers the return format (widget with cart items and checkout URL) and when to use it. It doesn't mention the optional 'strategy' parameter, but the schema covers that, and the description's focus on the two primary modes is sufficient for an agent to invoke 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 coverage is 100% since every parameter has a description, but the description adds value by explaining the relationship between the 'products' array and 'query' string: products takes precedence, and query is used only if products is not provided. This conditional logic goes beyond the schema's individual definitions.

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

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

The description opens with a specific verb+resource: 'Create a buyable shopping cart with a real checkout URL.' It clearly differentiates from browsing/recommendation tools by explicitly telling the agent to use search_products or skincare_recommend first, establishing its unique role.

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 includes an explicit exclusion: 'Do not use for browsing or recommendations — use search_products or skincare_recommend first.' It also describes two usage modes with clear conditions: pass a 'products' array for specific items or a 'query' string for auto-recommendations, giving the agent clear selection criteria.

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. The description adds behavioral context: it analyzes ingredients, irritation risk, and compatibility, and returns scored products with explanations, usage instructions, and Shopify checkout. This goes beyond the annotations without contradiction, though it does not detail every output edge case.

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 informative but slightly verbose, containing five sentences. It is front-loaded with the deprecation warning, and every sentence provides distinct value (purpose, usage, exclusions, return format, differentiation). A more concise version could tighten it, but the structure is logical and easy to scan.

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

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

No output schema exists, but the description specifies return contents (scored products, explanations, usage instructions, Shopify checkout). It also covers use cases, limitations, deprecation status, and comparison to siblings, making it complete for a recommendation 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?

Schema description coverage is 100% for all three parameters (brand, query, strategy), so the schema already carries parameter meaning. The description does not add additional parameter-specific detail; it focuses on higher-level behavior, 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 clearly states it provides personalized product recommendations with ingredient-aware scoring, safety notes, and routine building. It differentiates from siblings by explicitly deprecating in favor of 'recommend' and contrasting with search_products for browsing/listing.

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 scenarios (advice, choosing between products, specific skin concerns, routine building, 'what should I use for X') and when-not-to-use (browsing/listing, directing to search_products). It also explicitly prefers this tool over search_products for guidance, covering both inclusion and exclusion.

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

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

The annotations indicate readOnlyHint=false (write) and destructiveHint=false. The description adds that it 'helps improve the engine,' but does not disclose further behavioral details such as whether the report is asynchronous, logged, or has any side effects. With annotations present, the bar is lower, so a 3 is appropriate.

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

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

The description is three sentences: first states purpose, second gives usage scenarios, third explains rationale. It is front-loaded and every sentence contributes, with 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?

The description provides sufficient context for a simple reporting tool: purpose, when to use, and why. It does not explain what happens after reporting (e.g., no immediate visible effect), but the full schema coverage and simple nature make it mostly 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 schema covers 100% of parameters with descriptions, including tool_name, issue_type, user_query, description, and expected_products. The description adds no parameter semantics or usage details beyond what the schema provides, so the baseline 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 clearly states the tool's function: 'Report when a tool result was unhelpful, incomplete, or wrong.' This uses a specific verb (report) and resource (tool result issue), and distinguishes it from sibling tools by being the only issue-reporting tool.

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 states when to call: 'Call this whenever you override a recommendation, skip a cart result, or notice the engine output doesn't match what the user needs.' It also provides an exclusion: 'Do not use proactively — only when you observe an actual issue.' This leaves no ambiguity about when to use it.

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