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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds valuable behavioral details by stating it returns 'structured comparison with shared attributes, differences, tradeoffs, and a decision hint', which goes beyond the schema and 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 tightly written sentences: purpose, usage guidance, and output summary. Every sentence adds value with no filler or 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 simple input (one array parameter), strong annotations, and absence of an output schema, the description adequately covers what the tool does, when to use it, what it returns, and how it differs from siblings. No meaningful 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 description coverage is 100% — the 'products' parameter includes a clear description with format and example. The tool description doesn't add extra parameter-level semantics beyond what's in 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 tool's function with a specific verb ('Compare') and resource ('two or more products side by side'). It also distinguishes from sibling tools by explicitly contrasting with get_product for single lookups, making its 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?

Provides explicit usage conditions ('when the user asks to compare, says 'X vs Y', or wants to decide between options') and a clear exclusion with an alternative ('Do not use for single product lookup — use get_product instead'). This is textbook 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 (readOnly=false, openWorld=true) are present and not contradicted. The description adds behavioral notes beyond the flags: the URL-to-variant resolution 'happens automatically — no catalog import needed' and the result is a direct, clicking Shopify checkout link; that gives the system a clear model of what invokaking the tool accomplains. It doesn't mention the authority-gated decision_id path, but the schema documents that case, so the safety profile is covered.

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

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

Four sentences, each earning its place: core purpose, the auto-resolution behavior, the supported feature set, and a guardrail plus return format. It is front-loaded with the most important information and keeps feature listing to one sentence. Only a minor polish benefit would come from more trimming.

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 5-parameter, no-output-schema tool, the description covers the essential agent decision: what the tool does, when to use it, how to route (URLs vs variant IDs), and what is returned (a Shopify checkout link). The authority-gated requirement (decision_id) is a niche configuration left to the schema; the description handles the common path completely.

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% — all 5 parameters (items, product_urls, note, discount_code, decision_id) already have meaningful descriptions, defaults, and constraints documented. The description adds framing that HTML and URL inputs are complementary and that URLs auto-resolve, which is helpful but not required to compensate for any coverage gap. Baseline 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?

States a specific verb and resource: 'Create a checkout URL for one or more products.' The sentence 'Do not use unless the user wants to buy — use search_products or skincare_recommend first' sharpens the boundary with the sibling recall/recommend tools, so an agent can select this tool without opening its schema.

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-not-to-use guidance ('Do not use unless the user wants to purchase') and names alternatives to call first (search_products, skincare_recommend). It also explains that both variant IDs (items, product URLs (product_urls) are acceptable inputs, so there is no ambiguity about how to assemble the call.

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 and destructiveHint=false, so the safety profile is covered. The description adds that the tool 'Returns a widget card with the product details, image, price, and checkout button,' which informs the agent of the output structure beyond the annotations. No additional side-effect warnings are needed for a read-only lookup.

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, each with a distinct purpose: primary action, usage context, and exclusion/return. It is concise without redundancy and front-loads the most critical 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?

For a simple read-only product lookup with two parameters, the description covers purpose, usage boundaries, and return format. No output schema is needed for a widget card, and the tool's behavior is fully described with the context and exclusions.

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 both sku and title, including an example SKU and fuzzy-match note. The description's mention of 'by SKU or title' adds no new information beyond the schema, so a 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 opens with 'Get full details for a specific product by SKU or title,' providing a clear verb, resource, and lookup method. It explicitly differentiates from browsing/recommendation tools by directing to search_products or skincare_recommend, removing ambiguity among siblings.

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 states 'Use when the user asks about a specific product by name (e.g. ...)' and provides explicit exclusions: 'Do not use for browsing or recommendations — use search_products or skincare_recommend.' This gives 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. The description adds that it returns the summary and URL, which is useful behavioral context. It does not contradict the annotations and provides some extra value beyond the structured data.

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

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

A single, focused sentence that front-loads the action and resource. Every word earns its place; no redundant 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 simple one-parameter, read-only tool with no output schema, the description covers the essential info: what the tool does, what it returns, and where the parameter comes from. It is complete for the tool's 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% for the single parameter 'slug', so the baseline is 3. The description adds provenance by noting the slug comes from search_research_notes, which goes beyond the schema's example and clarifies the parameter's source.

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

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

The description clearly states the action ('Get'), the resource ('Research Note'), and the specific output ('summary and URL'). It distinguishes itself from sibling tools like search_research_notes by focusing on a single note identified by slug, which is precise and 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?

It provides clear contextual guidance by noting the slug is 'returned by search_research_notes', implying a two-step workflow: search first, then retrieve details. This indicates when to use this tool relative to its sibling. It lacks explicit exclusions, but the workflow hint is valuable.

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 enriches beyond annotations by detailing the return payload: 'scored products with checkout URLs, safety assessment, and authority state (SHOULD/CAN/SHOULDNT/ESCALATE/CANT).' This provides concrete information about the tool's behavior and output, going well beyond the simple readOnlyHint and destructiveHint 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 that front-load the core purpose and usage, followed by return details. Each sentence adds essential information without fluff or repetition. This is a model of concise, well-structured documentation.

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 no output schema, the description compensates by explaining the return values and authority states, which is critical for the agent. It also covers usage guidance. However, it does not disambiguate from the sibling tool skincare_recommend, which could lead to incorrect selection in edge cases.

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

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

Schema coverage is 100% with descriptive parameter definitions. The description does not add much parameter-specific semantics beyond what is already in the schema, such as 'query' being a natural language request. Baseline 3 is appropriate since the schema carries the burden.

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, safety notes, and transaction authority.' It specifies the resource and action. While it distinguishes itself from siblings like search_products by focusing on recommendations, it does not explicitly differentiate from the similarly named skincare_recommend, leaving some ambiguity.

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 usage context: 'Use when the user wants advice, has a concern, or asks what to buy.' This gives clear guidance on when to invoke the tool, but it does not mention when not to use it or suggest alternatives among the 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 destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it returns all matching products with prices, images, and checkout, does not score or filter, and shows everything so the user can decide. This goes beyond what annotations alone convey.

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

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

The description is longer than ideal, but every sentence carries weight. It front-loads the primary purpose, then addresses when-not-to-use, return contents, and key behavioral distinctions. No fluff, but readability could be tightened slightly.

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 4 parameters and no output schema, the description covers return values (prices, images, checkout), comparison to the recommendation sibling, and parameter usage guardrails. It does not mention pagination or sorting, but given max_results is documented, this is sufficient for a search/browse 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 coverage is 100%, so all parameters are documented. The description adds practical nuance: query examples, a strong caveat on the category parameter ('Do not guess categories'), and clear guidance on max_results behavior ('Only set this if the user specifies a count'). This improves usability beyond raw 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 the tool browses and searches the product catalog, with specific usage scenarios ('see what's available, look up specific products, browse by category, compare options'). It explicitly distinguishes itself from skincare_recommend, making the purpose unambiguous and differentiating it from siblings.

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 and an explicit exclusion: 'Do not use when the user needs personalized recommendations based on skin concerns — use skincare_recommend instead.' This leaves no ambiguity about which sibling to invoke.

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 covered. The description adds behavioral context beyond that by specifying the content scope (data studies, playbooks, field notes on agentic commerce) and the return fields (titles, summaries, URLs). While it doesn't discuss pagination or limits, for a simple read-only search this is reasonably transparent.

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 exactly two sentences and front-loaded with the action ('Search...'). It packs essential information—resource, content type, return values, and usage trigger—without any filler or redundant phrasing. Every clause earns its place.

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

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

For a tool with a single required parameter, read-only annotations, and no output schema, the description is sufficiently complete. It tells the agent what the tool does, what it returns, what kind of topics are covered, and when to use it. The lack of pagination or result-limit details is not a significant gap for a straightforward search 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?

The schema covers the single 'query' parameter with a description and examples, achieving 100% schema coverage. The tool description complements this by enriching the semantic context—e.g., listing specific topics like 'AI attribution', 'MCP', 'AI catalog accuracy', and 'ChatGPT ads'—which helps the agent formulate better queries. This is more than just a repetition of schema field names.

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 ('Search') and a clearly identified resource ('SearchShopAI's Research Notes blog'), and further defines scope with content types and example topics. It also states the return payload (titles, summaries, URLs), which gives a concrete sense of what the tool does. This strongly distinguishes it from sibling tools, especially get_research_note, by signaling search over retrieval.

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?

An explicit usage context is provided: 'Use when asked what SearchShopAI has written or published about a topic.' This gives the agent a clear trigger scenario. However, it does not explicitly mention when not to use it or point to an alternative tool (e.g., get_research_note for fetching a specific note), so it stops short of a full exclusion/alternative comparison.

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=true, destructiveHint=false), the description explains that the tool interprets the request and routes to appropriate capabilities, which is a meaningful behavioral trait not captured in annotations. It also specifies that it preserves qualifiers like concerns, skin type, and medical context, adding context about how it processes input.

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

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

The description is front-loaded with 'Start here for any shopping request' and uses concise, purposeful sentences. It provides necessary instructions and alternatives without redundancy, earning its length with concrete guidance and examples.

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 complex routing tool with no output schema, the description covers input expectations, routing capabilities, and guidance for follow-ups. It lacks details on return values or edge cases, but these are less critical for an entry-point tool. The overall guidance is sufficient for an agent to invoke it 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%, with each parameter already described as a 'secondary hint only' and the `request` field fully documented. The description reinforces the importance of passing the complete request, but adds no substantial new information beyond what the schema provides. Baseline 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 is an entry point for any shopping request, using a specific verb ('Start here') and explicitly distinguishes from sibling tools by listing the granular tools (search_products, get_product, compare_products, create_checkout) as precise follow-ups. It defines its scope as understanding and routing conversational requests.

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 gives explicit guidance: 'Prefer this tool whenever the request is conversational or carries any nuance' and states that granular tools remain available as follow-ups. This directly tells the agent 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?

The description discloses return behavior ('Returns a widget with the cart items and a working checkout link') and explains the two operational modes. Annotations already cover readOnly=false and destructiveHint=false, so the description adds value by specifying the output and the auto-recommend behavior of query mode. It does not discuss rate limits or side effects, but these are not hinted at by 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 three sentences with clear structure: purpose, mode list, exclusion, and return output. No redundant phrases or filler. It is front-loaded with the primary purpose and efficiently conveys all necessary pointers.

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 3 parameters, no required fields, and no output schema, the description covers the essential context: what it does, when to use, modes, and output. Minor gaps include not specifying behavior when both query and products are provided (though schema handles that) and absence of error-case handling, but these are partially covered by the schema and not critical for selection.

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% parameter coverage, so the baseline is 3. The description adds meaningful context by explaining the conditional relationship: products array is for 'specific product names' while query mode 'auto-recommend[s] and cart[s]', and that query is 'only used if products array is not provided' (though that detail is also in the schema). This helps the agent choose between mutually exclusive parameters.

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

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

The description explicitly states the tool's purpose with a specific verb and resource: 'Create a buyable shopping cart with a real checkout URL.' It also distinguishes itself from siblings like search_products and skincare_recommend by clarifying it's for cart creation, not browsing or recommending.

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 and when-not-to-use guidance: 'Do not use for browsing or recommendations — use search_products or skincare_recommend first.' It also details two distinct modes ('Pass products array' vs 'Pass query string') and conditions for each, aiding correct invocation.

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?

Annotations mark the tool as not read-only and not destructive, and the description adds that it helps improve the engine, implying a write/feedback action. However, it does not disclose side effects, such as whether reports are stored or if there are limits, leaving moderate behavioral transparency.

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 that front-load the primary action and then provide usage conditions and rationale. No filler words; every sentence 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?

For a simple feedback tool with full schema coverage and clear trigger conditions, the description is sufficient for correct invocation. It lacks an explicit mention of the expected response, but no output schema exists and the function is straightforward, so a small gap remains.

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 all five parameters are documented (tool_name, issue_type, user_query, description, expected_products). The description does not add extra parameter-level detail, but the schema already carries the burden, 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 uses a specific verb ('Report') and clearly identifies the resource (tool result issues), distinguishing it from sibling recommendation/cart tools. It explains the tool's role in flagging unhelpful, incomplete, or wrong results, which is unique among siblings.

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 it ('whenever you override a recommendation, skip a cart result, or notice the engine output doesn't match...') and when not to ('Do not use proactively — only when you observe an actual issue'). This provides clear decision rules without needing separate alternative tools.

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