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, which the description aligns with. The description adds behavioral context (two modes for devices vs topicals) beyond annotations, enhancing 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 with no fluff. First sentence states purpose, second explains dual behavior, third gives usage examples. Information is front-loaded and 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?

Lacks description of output format or what 'compatible' means in the response. With no output schema, the agent might need to guess the return shape. However, the examples imply a list, and the tool's simplicity partially compensates.

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

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

Schema coverage is 100% with a clear description for the 'product' parameter. The description adds value by explaining how the parameter is used in two compatibility scenarios (device->consumable, topical->device), which aids agent understanding.

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 specific verb 'Check' and resource 'compatible products', clearly distinguishes from siblings like compare_products and recommend, and gives concrete examples for devices and topicals.

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 with example customer queries ('what gel do I need with MIRA?', 'does this serum work with CryoSculpt?'), providing clear context. Does not explicitly state when not to use, but examples suffice.

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 agent knows it's a safe read operation. The description adds that it uses the Shopify Storefront API for real-time verification, which is helpful but not essential beyond the annotations.

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

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

Two sentences, no wasted words. The key action is front-loaded, and the usage guidance is concise.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete enough. It could mention the return type (e.g., boolean or stock level), but the current context is 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?

Schema coverage is 100% with a clear description of the parameter. The description does not add additional semantics beyond what's in 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 clearly states the tool checks product availability, with a specific verb ('Check if a product is currently available') and resource ('inventory'). It distinguishes itself from siblings like 'check_compatibility' and 'recommend' by focusing on stock status.

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 when to use the tool ('when a customer asks 'is MIRA in stock?' or before recommending a product'), providing clear context. It does not explicitly mention when not to use it, but the guidance is sufficient.

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 clear. The description adds value by detailing the return structure (shared attributes, differences, tradeoffs, decision hint), which is useful for an agent. 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?

Three sentences with no wasted words. The core purpose is front-loaded in the first sentence, and the description efficiently covers usage guidance and output 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?

Despite having no output schema, the description sufficiently explains the return value. For a simple comparison tool with one parameter and good annotations, the description is complete and covers all necessary aspects.

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% and the parameter 'products' is well-described in the schema (array of strings, min/max items, description). The tool description does not add additional semantics beyond what the schema provides, 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 'Compare two or more products side by side', specifying the action (compare) and resource (products). It explicitly distinguishes from sibling tools by directing single product lookups to get_product.

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 ('user asks to compare, says 'X vs Y', or wants to decide between options') and when-not-to-use ('Do not use for single product lookup — use get_product instead'), along with description of the return value.

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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds valuable behavioral details: it resolves product URLs to variant IDs automatically without needing a catalog import, returns a Shopify checkout link, and supports discount codes. However, it does not mention authentication requirements, rate limits, or error handling, which would enhance 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?

The description is concise (four sentences) and well-structured. It starts with the primary purpose, then explains the two input methods, followed by key features, and ends with usage guidance. 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 tool has 5 parameters, no output schema, and moderate complexity, the description covers the main aspects: what the tool does, how to provide products, and the ordering workflow relative to siblings. It does not detail what happens when both items and product_urls are provided, or how to handle errors, but for a checkout tool this is sufficient.

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 parameters. The description adds context beyond the schema: it explains the distinction between 'items' (variant IDs) and 'product_urls' (URLs that are auto-resolved), and mentions that product_urls bypass catalog import. This adds meaningful semantics to the 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 clearly states the tool creates a checkout URL for products. It specifies the two input methods (variant IDs and product URLs) and distinguishes from sibling tools by explicitly noting when not to use it (e.g., 'Do not use unless the user wants to buy — use 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?

The description provides explicit when-to-use and when-not-to-use guidance ('Do not use unless the user wants to buy — use search_products or skincare_recommend first'). It also lists supported features (discount codes, cart notes, selling plans), giving clear context for usage.

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 readOnly=true and destructive=false. The description adds context about asking for discount codes, which is conversational. No contradictions, but could clarify that it does not actually apply discounts.

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, each with a clear purpose: definition of tool, usage triggers, and an actionable instruction. No extraneous 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 tool with one optional parameter, the description covers when, what, and the key behavior. Could mention that discounts are not applied by this tool, but overall complete.

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

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

Schema coverage is 100% with parameter 'discount_code' described. The description adds value by linking the parameter to the action of asking the customer, providing behavioral context 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 shows bundles, deals, and asks about discount codes, distinguishing it from sibling tools like recommend or check_inventory.

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 specifies when to use: when customers ask about deals, bundles, savings, or have discount codes, and when multiple items are in cart. Also gives an imperative to always ask for a 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 readOnlyHint=true and destructiveHint=false, and the description adds that it returns a widget card with product details, image, price, and checkout button, confirming read-only behavior. 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?

Two sentences: first states purpose, second provides usage guidance and return info. No redundant words, front-loaded with key 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?

Covers purpose, usage, and return format sufficiently. Could mention what happens if product not found or if both parameters provided, but overall complete for a simple read 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 has 100% coverage with descriptions for both parameters (sku and title). The description reiterates these as lookup methods but does not add new semantics beyond the schema. 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 starts with a clear verb 'Get' and specific resource 'full details for a specific product by SKU or title'. It distinguishes from sibling tools like search_products and skincare_recommend by specifying exact lookup vs browsing/recommendations.

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') and provides alternative tools ('use search_products or 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 declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description adds that it returns summary and URL specifically. No contradictions, but no further behavioral details 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?

Single sentence, no wasted words. Front-loaded with action and resource. Efficient and to the point.

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?

Tool is simple with one parameter and no output schema. Description clarifies return fields (summary and URL) and origin of slug. Adequate for a single-note retrieval tool, though lacks response structure details.

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

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

Schema coverage is 100% with a well-described slug parameter including maxLength and example. The description does not add additional meaning beyond the schema; 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 action 'Get the summary and URL' and the resource 'Specific SearchShopAI Research Note', and specifies the method 'by its slug'. It also distinguishes from sibling search_research_notes by noting the slug comes from that 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?

The description implies usage sequence: first use search_research_notes to get slugs, then this tool. It does not explicitly state when not to use or list alternatives, but the context is clear enough for an agent to infer correct usage.

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 description adds value by detailing the output: scored products with safety assessment and authority state. It discloses behavioral traits beyond annotations without 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?

Three concise sentences, each serving a distinct purpose: purpose, usage, and output. No redundant or extraneous information.

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

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

The description covers purpose, usage, and output elements (scored products, checkout URLs, safety, authority). However, with no output schema, it lacks structural details like format or pagination, which would be helpful 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 tool description does not add extra semantics for parameters, relying on the schema descriptions which are already present.

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 begins with a clear verb and resource: 'Get a personalized product recommendation'. It distinguishes itself from siblings by highlighting domain-expert scoring, safety notes, and authority state, which are unique features not seen in sibling names like 'search_products' or 'shop'.

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: 'Use when the user wants advice, has a concern, or asks what to buy.' This provides clear contextual guidance, though it does not mention when not to use or name specific 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 declare readOnlyHint=true and destructiveHint=false, which the description aligns with. The description adds that the tool returns matching products with prices, images, and checkout, and that it does not score or filter like skincare_recommend. This enriches transparency beyond annotations, though it could mention pagination or rate limits.

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, well-structured with clear sections: purpose, usage guidelines, return behavior, and comparison. Every sentence earns its place; no redundancy. Front-loaded with the primary purpose.

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 4 parameters, no output schema, and the tool's search/browse nature, the description covers expected usage, edge cases (when not to use), and return behavior. The sibling list provides further context. 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 coverage is 100%, so baseline is 3. The description adds context for the category parameter ('Do not guess categories – only use if user explicitly mentions a catalog category'), which adds decision-making value beyond the schema. No major gaps, but does not elaborate on max_price or max_results beyond schema defaults.

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: 'Browse and search the product catalog.' It lists specific use cases (look up products, browse by category, compare options) and distinguishes from sibling tool skincare_recommend. The verb 'search' and resource 'product catalog' are explicit.

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 ('user wants to see what's available...') and when-not-to-use ('Do not use when user needs personalized recommendations – use skincare_recommend instead'). Also explains behavioral difference from the sibling tool, giving clear guidance on tool selection.

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. Description adds that it returns articles with titles, summaries, and URLs, providing useful behavioral context beyond annotations. No contradictions.

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

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

Two sentences, no wasted words. First sentence states purpose and examples, second sentence states when to use. Well-structured and front-loaded.

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

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

For a tool with one parameter and no output schema, the description adequately covers input, output, and usage context. 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?

Only one parameter 'query' with schema description and maxLength. The description provides example values like 'attribution', 'MCP', adding practical 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 it searches SearchShopAI's Research Notes blog and returns matching articles with titles, summaries, and URLs. It includes example topics like 'attribution', 'MCP', etc., and distinguishes from sibling get_research_note which retrieves a single note.

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 asked what SearchShopAI has written or published about a topic.' This provides clear context, though it does not list alternatives or when not to use. Sibling tools like search_products or check_compatibility are clearly different.

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: the tool understands natural language, routes to capabilities, and preserves qualifiers. It does not contradict annotations and provides useful insight beyond them.

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 the key instruction, and every sentence adds value. No redundancy or wasted words. The structure makes it easy for an agent 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 complexity (5 parameters, 14 sibling tools, no output schema), the description explains the tool's role and relation to siblings. However, it does not describe the return format or what the agent can expect after routing, which is a gap. Output schema is absent, so the description should hint at output structure.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by emphasizing to pass the shopper's complete request verbatim and noting that other parameters are secondary hints. This reinforces correct usage.

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: 'Start here for any shopping request.' It specifies the verb ('route') and the resource ('shopping request'), and distinguishes from sibling granular tools by explicitly naming them 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 provides explicit guidance: 'Prefer this tool whenever the request is conversational or carries any nuance.' It also indicates when not to use it by referencing granular tools as alternatives for 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?

Annotations indicate mutability (readOnlyHint=false) and the description clarifies it creates a cart and returns a working checkout link. However, it does not disclose potential side effects like cart persistence or cart lifetime, which would be helpful for complete 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?

The description is exceptionally concise at 4 sentences, front-loading the core purpose and then breaking down modes and exclusions. Every sentence adds non-redundant information, making it efficient for an AI agent 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 has no required parameters and no output schema, the description fills the gap by stating what is returned ('a widget with the cart items and a working checkout link'). It covers the primary behavior, but could mention edge cases like what happens if both modes are invoked or if no products are found.

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 good descriptions for all three parameters (100% coverage). The tool description adds value by explaining the two usage modes and how parameters interact (e.g., 'query' used only if 'products' not provided), which is not evident from the schema alone.

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

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

The description starts with a clear verb-resource pair ('Create a buyable shopping cart') and specifies two distinct modes (products array vs query). It also explicitly distinguishes itself from sibling tools like search_products and skincare_recommend, 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?

The description gives explicit when-to-use ('to create a cart with checkout URL') and when-not-to-use ('Do not use for browsing or recommendations'), along with clear alternative tools ('use search_products or skincare_recommend first'). This provides excellent guidance for an AI agent.

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

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

Annotations already indicate read-only and non-destructive behavior. Description adds value by explaining it analyzes ingredients, irritation risk, and product compatibility, and returns scored products with explanations and checkout. 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?

Description is comprehensive yet efficient, starting with deprecation notice, then purpose, usage guidelines, and behavioral details. Each sentence serves a purpose, though slightly verbose with redundant clarification.

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 3 parameters, no output schema, and annotations present, the description covers the tool's purpose, usage context, return value (scored products with explanations), and sibling differentiation. Could hint at pagination or limits but adequate for decision-making.

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

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

Schema has 100% coverage with detailed descriptions for all three parameters. Description does not add significant parameter-specific information beyond what schema provides, though it reinforces the natural language use case for query.

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 provides personalized product recommendations with ingredient-aware scoring, safety notes, and routine building. It explicitly distinguishes from siblings like search_products (for browsing) and recommend (deprecation alias).

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, has skin concerns, needs routine) and when not to use (browsing/listing products, directs to search_products). Also identifies the replacement tool (recommend) due to deprecation.

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 no special read-only, open-world, or destructive hints. The description clarifies it is a feedback mechanism ('This helps improve the engine'), implying a side-effect operation. No contradiction, and it adds behavioral 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?

The description is only three sentences, front-loaded with the core purpose, followed by usage examples and a boundary. 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?

For a feedback tool with five parameters (three required) and no output schema, the description sufficiently covers purpose, usage, and behavioral context. No additional details on return values are needed.

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

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

Schema coverage is 100% with all five parameters described in the schema. The description does not add additional parameter details beyond the schema, which is acceptable at the baseline of 3.

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: to report when a tool result was unhelpful, incomplete, or wrong. It uses specific verbs ('report', 'call this whenever') and distinguishes from siblings by being a feedback tool, not a recommendation or cart 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?

The description provides explicit guidance on when to use the tool ('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 clearly differentiates from alternative actions.

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