Apostle — AI Men's Skincare Commerce

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 context about the bidirectional nature of compatibility (device->consumables, topicals->devices). No additional behavioral traits disclosed 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?

Three sentences with no wasted words. First sentence states purpose, second clarifies two cases, third provides example queries. 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?

For a simple read-only tool with one parameter and no output schema, the description sufficiently covers purpose, usage examples, and result interpretation. No gaps identified.

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 for 'product' is present, but the tool description adds meaningful context about how the result differs based on product type (device vs topical). This helps the agent interpret the output correctly.

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

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

Clearly states the tool checks compatibility of products, with specific examples for devices and topicals. Distinguishes from sibling tools like compare_products or check_inventory by listing concrete use cases.

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 says when to use this tool with example customer queries. Lacks explicit when-not-to-use or mention of alternatives, but the examples are clear and cover common scenarios.

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=true and destructiveHint=false. The description adds value by specifying the API source (Shopify Storefront) and real-time nature. It does not conflict with annotations. However, it lacks details on response format or edge cases like out-of-stock scenarios.

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 highly concise with two focused sentences, no redundancy, and front-loads the core purpose. Every sentence adds value, making it efficient for agent parsing.

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 lacks details about the return format (e.g., boolean, stock count, or structured data) since there is no output schema. Given the tool's simplicity, this is a moderate gap; a note on what the agent can expect would improve 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?

Schema coverage is 100%, with a single parameter 'product' having a clear description in the schema. The description minimally adds context by implying the parameter is a product identifier, but does not enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: checking if a product is currently available using the Shopify Storefront API for real-time stock status. It also provides an example of when to use it, distinguishing it from sibling tools like 'get_product' or 'search_products' by focusing solely on 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 explicitly says to use this tool when a customer asks 'is MIRA in stock?' or before recommending a product, providing clear context. However, it does not explicitly state when not to use it or suggest alternative tools, leaving some ambiguity.

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 read-only nature is covered. The description adds value by describing the output structure (shared attributes, differences, tradeoffs, decision hint) 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?

Three sentences with no fluff: purpose, usage guidance, and return description are all front-loaded. 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?

The tool has one well-documented parameter, annotations are present, and no output schema is needed. The description fully covers when to use, what it does, and what it returns.

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 'products' is well-documented in the schema with example values. The description does not add further parameter-level details, 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?

Description clearly states 'Compare two or more products side by side' with a specific verb and resource. It distinguishes from sibling 'get_product' by specifying not for single product lookup, and mentions the return structure.

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 says 'Use when the user asks to compare, says X vs Y, or wants to decide between options' and provides a direct alternative: 'Do not use for single product lookup — use get_product instead.'

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?

Discloses key behaviors: automatic resolution of product URLs to variant IDs, support for discount codes, cart notes, and selling plans. Annotations confirm write operation (readOnlyHint=false) without contradiction. Adds context about return value and decision_id condition.

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?

Front-loaded with main purpose, every sentence provides essential information without redundancy. Concise yet comprehensive, fitting all necessary details in 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?

Despite no output schema, description clarifies return value ('direct Shopify checkout link'). Covers all relevant aspects: input methods, supported features, prerequisites (e.g., decision_id for authority-gated checkout), and use case constraints.

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 all parameters. Description adds significant value by explaining the relationship between 'items' and 'product_urls', the automatic resolution behavior, and usage context for parameters like 'note' and 'discount_code'.

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

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

Clearly states it creates a checkout URL for products. Specifically mentions inputs (variant IDs and product URLs) and distinguishes from sibling tools by recommending search_products or skincare_recommend first.

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 use ('Do not use unless the user wants to buy') and provides alternatives ('use search_products or skincare_recommend first'), giving clear guidance for agent decision-making.

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, so the tool is safe. Description adds context that it shows deals and asks for codes, which complements annotations. No contradiction or missing behavioral traits.

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 concise sentences: purpose, when-to-use, and required action. Front-loaded and no wasted words.

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

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

Given one optional parameter, no output schema, and annotations covering safety, the description fully equips an agent to understand 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 has 100% coverage with one parameter described. Description reinforces that the discount_code parameter is optional and should be asked for, adding value beyond the schema description.

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 shows available bundles, deals, and asks about discount codes. It uses specific verbs and resources, and distinguishes from siblings like get_product or search_products.

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

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

Explicit guidance on when to use: when customer asks about deals, bundles, savings, or 'have any discounts?', and when multiple items in cart to suggest bundle savings. Also instructs to always ask for discount code.

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 the tool as read-only and non-destructive. Description adds behavioral context by stating it returns a widget card with product details, image, price, and checkout button. 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?

Three concise sentences with clear front-loading. Every sentence adds essential information: function, usage guidance, and return description.

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 lookup tool with 2 fully-described parameters and no output schema, the description adequately explains input and output. No missing context.

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

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

Schema covers both parameters with full descriptions. Description mentions SKU and title but adds no new meaning beyond what schema already provides (e.g., 'Exact product SKU', 'fuzzy match'). Baseline 3 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?

Description clearly states 'Get full details for a specific product by SKU or title', uses specific verb and resource. Distinguishes from siblings by explicitly contrasting with browsing/recommendation tools, and names 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?

Explicitly states when to use ('when the user asks about a specific product by name') and when not to use ('Do not use for browsing or recommendations'). Mentions specific alternatives: search_products and skincare_recommend.

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, destructiveHint=false) already declare the tool is safe and read-only. The description adds value by specifying the exact return content (summary and URL), which is 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?

The description is a single sentence of 18 words that efficiently conveys the action, resource, input, and source of the input. No unnecessary words or repetition.

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

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

Given the tool's simplicity (one read-only parameter, no output schema), the description provides sufficient information: what it does, what it returns, and how to get the input. It could mention error handling or return format details, but those are less critical for this straightforward retrieval.

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 slug parameter fully with a description and example. The description adds context by indicating the slug is obtained from search_research_notes, which is helpful but not critical. As schema coverage is 100%, baseline 3 applies, but the extra provenance information raises it to 4.

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

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

The description clearly states the verb 'Get' and the resource 'summary and URL of a specific SearchShop AI Research Note', and distinguishes it from a sibling tool by mentioning that the slug is returned by search_research_notes.

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 guides usage by stating that the slug comes from search_research_notes, suggesting a workflow. However, it does not explicitly state when not to use it or provide alternative tools, though the sibling list provides context.

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 and destructiveHint=false, confirming safe read. The description adds valuable behavioral context: it returns scored products with checkout URLs, safety assessment, and an authority state (SHOULD/CAN/SHOULDNT/ESCALATE/CANT). 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 concise with three sentences. The first sentence clearly states purpose and features, the second gives usage guidance, and the third details output contents. No unnecessary 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 complexity (4 parameters, no output schema), the description sufficiently covers input requirements, usage, and output details (scoring, safety, authority, checkout URLs). It lacks mention of error handling or limits, but annotations provide non-destructive context, making it adequately complete for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new information about parameters beyond what the schema already provides. It mentions 'query' as natural language, but that is already in the schema. No extra semantics for brand, domain, or strategy.

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 provides a personalized product recommendation with domain-expert scoring, safety notes, and transaction authority. It uses a specific verb ('Get') and resource ('personalized product recommendation'), and distinguishes from siblings like 'skincare_recommend' by mentioning cross-domain expertise and authority state.

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 states when to use the tool: 'Use when the user wants advice, has a concern, or asks what to buy.' This provides clear context. However, it does not specify when not to use it or mention alternative tools for specific scenarios, such as compatibility checks 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 are consistent (readOnlyHint=true, destructiveHint=false). The description adds context by stating the tool returns all matching products with prices, images, and checkout, and that it does not score or filter. This goes beyond annotations to explain behavior.

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

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

The description is concise (two sentences plus a note) and front-loaded with the main purpose and usage. Every sentence adds value, with no wasted words. The structure is efficient and easy to parse.

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 complexity (4 parameters, no output schema), the description is complete. It covers purpose, usage guidelines, return content (prices, images, checkout), and differentiation from siblings. Annotations already cover safety, so the description focuses on what the agent needs 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 description coverage is 100%, so baseline is 3. The description adds value by explaining 'max_results' default behavior and when to set it, and clarifies that 'category' should only be used when the user explicitly specifies a catalog category. This provides practical usage guidance beyond the schema.

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

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

The description clearly states the tool's purpose: browsing and searching the product catalog. It specifies when to use it (user wants to see available products, look up items, browse by category, compare options) and explicitly distinguishes it from sibling tool skincare_recommend. This provides a specific verb and resource with clear 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 usage guidelines: 'Use when...' and 'Do not use when...' with a direct alternative (skincare_recommend). It also clarifies that the tool does not score or filter like the alternative, 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 (readOnlyHint=true, destructiveHint=false) already indicate safe read operation. Description adds return format details (articles with titles, summaries, URLs). No behavioral gaps or 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?

Two sentences with no wasted words. Purpose is front-loaded, and usage guideline follows immediately. Highly concise and well-structured.

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 tool with no nested objects and no output schema, the description adequately covers purpose, usage, and return format. Mentions the blog source and types of content, which is sufficient context.

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

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

Schema coverage is 100% with a single 'query' parameter described with examples. Description repeats similar info ('Topic or keywords') without adding new meaning beyond the schema, so 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 the tool searches SearchShop AI's Research Notes blog for articles on specific topics, returning titles, summaries, and URLs. It differentiates from siblings like search_products (product search) and get_research_note (single note 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?

Includes explicit usage guidance: 'Use when asked what SearchShop AI has written or published about a topic.' Provides clear context without specifying exclusions or alternatives, but effectively indicates when to use the 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. Description adds that the tool will 'understand' and 'route to the right capability,' which is useful behavioral context. 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?

Description is two paragraphs, each sentence adds value: first introduces the tool, second gives usage guidance and alternates. No fluff 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 tool's complexity as a router and the lack of output schema, the description adequately explains the tool's purpose, parameter usage, and relationship to siblings. Could mention response format, but not necessary due to 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 coverage is 100%, baseline 3. Description adds value by emphasizing that 'request' should be the complete request in the shopper's own words, and that other parameters are 'secondary hints only,' which clarifies their limited role.

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 'Start here for any shopping request' and explains it routes requests to capabilities (recommendation, search, etc.). Explicitly distinguishes from sibling granular tools by saying 'Prefer this tool whenever the request is conversational or carries any nuance.'

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?

Clearly says when to use: 'Start here for any shopping request' and 'Prefer this tool whenever the request is conversational or carries any nuance.' Also indicates when not to use by listing granular tools as 'precise follow-ups.'

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 that the tool creates a cart with a checkout URL, operates in two modes, and returns a widget with cart items and a checkout link. This adds contextual value beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by explaining the cart creation and return format.

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 long, front-loaded with the core purpose, and every sentence adds essential information without 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 tool's moderate complexity (no output schema, no nested objects, 3 parameters with 100% coverage), the description adequately covers the two modes, return value (widget with cart items and checkout link), and usage constraints. No missing critical information.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the two-mode distinction (products array vs query string) but does not add significant detail beyond what the schema provides for each parameter. Baseline 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 the tool creates a buyable shopping cart with a real checkout URL, specifies two distinct modes (products array or query string), and explicitly distinguishes it from sibling tools by directing browsing and recommendation tasks to search_products or skincare_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?

The description explicitly tells when to use this tool (to create a buyable cart) and when not to use it (not for browsing or recommendations), and directly names alternative tools (search_products, skincare_recommend) that should be used instead.

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?

Discloses behavior beyond readOnlyHint: analyzes ingredients, irritation risk, product compatibility; returns scored products with explanations, usage instructions, and Shopify checkout. No contradiction with annotations.

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

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

Well-structured with deprecation warning first, then purpose, usage conditions, and behavior. Every sentence adds value; could be slightly shorter but not wasteful.

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 readOnlyHint and no output schema, description covers return format (scored products, explanations, usage, checkout), when to use, and deprecation context. Complete for its 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?

100% schema coverage means baseline is 3, but description adds meaningful context: explains query is natural language, strategy is optional override, and brand filter. Adds value 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 deprecated status but explains tool's function: personalized product recommendation with ingredient-aware scoring, safety notes, and routine building. Distinguishes from sibling search_products by specifying it's for guidance, not 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?

Explicitly states when to use (user wants advice, choosing between products, specific skin concern, routine) and when not to use (browsing/listing), with direct alternative (search_products). Also mentions deprecation and suggests using 'recommend' instead.

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=false, openWorldHint=false, destructiveHint=false, but the description adds that reporting helps improve the engine, which is a non-destructive feedback action. 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 extremely concise—two sentences that front-load the purpose and provide actionable usage rules. Every sentence adds value without 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 absence of an output schema and the tool's simple feedback purpose, the description provides sufficient context for an agent to know when and how to use it. It covers the required parameters implicitly through the description of tool_name, issue_type, and description.

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. The tool description does not add additional parameter semantics beyond what the schema already provides, 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 clearly states the tool's purpose: reporting issues with tool results. It specifies scenarios like overriding recommendations, skipping cart results, and noticing mismatches. This distinguishes it from sibling tools like skincare_recommend and skincare_cart.

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 (reporting unhelpful, incomplete, or wrong results) and a clear prohibition ('Do not use proactively'). While it doesn't explicitly list when not to use alternatives, the context makes the usage scope clear.

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