AI commerce for Shopify: product search, comparison, recommendations, and checkout via MCP.
Scored across 11 tools
Substantial overlaps exist: `recommend` and `skincare_recommend` are explicitly identical (one deprecated), `create_checkout` and `skincare_cart` both produce buyable checkout URLs, and the `shop` router conceptually subsumes search_products, get_product, compare_products, and recommend. Descriptions add routing guidance, but an agent still faces real redundancy and must pick between near-duplicate paths.
Names are uniformly snake_case, which is good, but the verb/prefix conventions are inconsistent: bare verbs (`shop`, `recommend`) mix with verb_noun (`get_product`, `search_products`, `compare_products`), and a `skincare_` domain prefix is applied to only some tools (`skincare_cart`, `skincare_recommend`, `skincare_report_issue`) while related tools lack it.
11 tools is a reasonable scope for a shopping/research assistant, though one tool (`skincare_recommend`) is deprecated and redundant, effectively leaving 10, and the router-plus-granular design adds a layer that is arguably unnecessary.
The surface covers the core shopping lifecycle well: discovery (search_products), lookup (get_product), decision (compare_products, recommend), purchase (create_checkout, skincare_cart), plus research notes and a feedback channel. Only minor gaps (e.g. order management, broader research retrieval) keep it from being fully complete.
Compare two or more products side by side. Use when the user asks to compare, says 'X vs Y', or wants to decide between options. Do not use for single product lookup — use get_product instead. Returns structured comparison with shared attributes, differences, tradeoffs, and a decision hint.
| Name | Required | Description | Default |
|---|---|---|---|
| products | Yes | Product titles or SKUs to compare (e.g. ['MIRA', 'CryoSculpt']) |
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.
Create a checkout URL for one or more products. Pass variant IDs (items) and/or product URLs (product_urls). When a product URL is provided (e.g. https://laluer.com/products/mira), the tool resolves it to a variant ID automatically — no catalog import needed. Supports discount codes, cart notes, and selling plans. Do not use unless the user wants to buy — use search_products or skincare_recommend first. Returns a direct Shopify checkout link the user can click to buy.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Cart note visible to the merchant | |
| items | No | Products to add to cart by variant ID | |
| decision_id | No | Optional — leave unset unless an earlier create_checkout error asked for it. | |
| product_urls | No | Products to add to cart by URL — resolved to variant IDs automatically | |
| discount_code | No | Discount code to apply (e.g. 'WELCOME10') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: product URLs are resolved to variant IDs automatically with no catalog import, and the return value is a clickable Shopify checkout link. It stops short of describing failure modes or what decision_id does (left to the schema), so a 4 rather than 5.
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 the core action in the first sentence, then progressively adds resolution behavior, supported features, the exclusion rule, and the return value. Every sentence carries distinct information; nothing is repeated from the schema.
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 correctly names the return value (a direct Shopify checkout link) and covers input modes and usage boundaries. Minor gaps remain around error/retry behavior tied to decision_id, which is only hinted at in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds the 'and/or' relationship between items and product_urls that the schema does not state (required params = 0), and surfaces the higher-level capabilities (discount codes, cart notes, selling plans) that map to individual params.
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') and goes further by explaining the two input modes (variant IDs vs product URLs) and the automatic URL-to-variant resolution. It is clearly distinguishable from siblings 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?
Contains an explicit exclusion with named alternatives: 'Do not use unless the user wants to buy — use search_products or skincare_recommend first.' This tells the agent both when not to call it and what to call instead, which is exactly the routing guidance siblings lack.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for a specific product by SKU or title. Use when the user asks about a specific product by name (e.g. 'tell me about MIRA', 'show me the serum'). Do not use for browsing or recommendations — use search_products or skincare_recommend. Returns a widget card with the product details, image, price, and checkout button.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | Exact product SKU (e.g. 'LL-4632379916336') | |
| title | No | Product title to search for (fuzzy match) |
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.
Get the summary and URL of a specific SearchShopAI Research Note by its slug (returned by search_research_notes).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The note slug, e.g. 'the-ai-attribution-blind-spot' |
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.
Get a personalized product recommendation with domain-expert scoring. Use when the user wants advice, has a concern, or asks what to buy. Returns scored products with checkout URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Filter to a specific brand | |
| query | Yes | Natural language query about product needs | |
| domain | No | Product domain (e.g. 'skincare', 'beauty_devices'). Auto-detected from merchant if omitted. | |
| strategy | No | Optional offer strategy override |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that results come 'with domain-expert scoring' and 'checkout URLs', but discloses no auth requirements, rate limits, or latency, so it contributes only modestly beyond the structured fields.
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 tight sentences that front-load the core purpose before the usage triggers and return note. No filler, though it is slightly terse for a tool with four parameters and a long sibling list.
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 usefully notes the return shape ('scored products with checkout URLs'), and usage triggers are given for the single required parameter. The main gap is the absence of any routing distinction from skincare_recommend, given the crowded sibling set.
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 brand, query, domain, and strategy are all documented in the schema (including domain auto-detection from merchant). The description adds nothing about parameter syntax, formats, or interactions, so the 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 (recommend) and resource (personalized products) plus a differentiating qualifier ('domain-expert scoring'). However, it never distinguishes itself from the overlapping sibling skincare_recommend, so an agent cannot fully disambiguate the two from the description alone.
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?
Gives concrete usage triggers ('user wants advice, has a concern, or asks what to buy'), which is clear context for invocation. It stops short of naming alternatives such as compare_products or search_products or stating when not to use it, so routing between siblings is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse and search the product catalog. Use when the user wants to see what's available, look up specific products, browse by category, compare options, or asks 'show me' / 'what do you have.' Do not use when the user needs personalized recommendations based on skin concerns — use skincare_recommend instead. Returns all matching products with prices, images, and checkout. Unlike skincare_recommend, this does not score or filter — it shows everything that matches so the user can decide.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (e.g. 'vitamin c serum', 'anti-aging', 'moisturizer under $50') | |
| category | No | Filter by exact product category from the catalog (e.g. 'serum', 'treatment', 'cleanser', 'moisturizer'). Do not guess categories — only use this if the user explicitly mentions a catalog category. For general queries like 'devices' or 'bundles', use the query parameter instead. | |
| max_price | No | Filter to products at or below this price | |
| max_results | No | Maximum products to return (default 10). Only set this if the user specifies a count — e.g. 'show me 2 devices' → 2. Otherwise leave it unset and the default will return all relevant matches up to 10. |
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.
Search SearchShopAI's Research Notes blog — data studies, playbooks, and field notes on agentic commerce (AI attribution, MCP, AI catalog accuracy, ChatGPT ads). Returns matching articles with titles, summaries, and URLs. Use when asked what SearchShopAI has written or published about a topic.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Topic or keywords, e.g. 'attribution', 'MCP', 'hallucinated prices' |
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.
Start here for any shopping request. Pass the shopper's COMPLETE request in their own words and this tool will understand it and route to the right capability (personalized recommendation, catalog search, product lookup, or comparison), preserving every qualifier — concerns, skin type, budget, brand. Prefer this tool whenever the request is conversational or carries any nuance. The granular tools (search_products, get_product, compare_products, create_checkout) remain available as precise follow-ups.
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Secondary hint only — brand filter if stated. | |
| intent | No | Secondary hint only — the primary signal is `request`. | |
| request | Yes | The shopper's complete request in their own words. Include every detail: concern, skin type, budget, brand, product names, questions. Do not summarize or drop qualifiers. | |
| budget_max | No | Secondary hint only — maximum budget if stated. | |
| product_refs | No | Secondary hint only — exact product titles/SKUs when already known. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the agent knows this is a safe, non-destructive, closed-world operation. The description adds the routing behavior and the instruction to preserve qualifiers, but says nothing about latency, failure modes, or the shape of what the router returns.
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 the imperative 'Start here for any shopping request,' and each subsequent sentence adds a distinct instruction (qualifier preservation, when to prefer, alternatives). Slightly verbose but 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?
For a router with no output schema and a fully documented input schema, the description covers the essential decisions: entry-point role, routing targets, and sibling relationships. It could say more about what the router returns or when it escalates, but the calling guidance is 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%, so the schema already documents all five parameters, including the note that intent/brand/budget_max/product_refs are 'secondary hints.' The description largely restates the request-parameter guidance ('Pass the shopper's COMPLETE request ... preserving every qualifier') that the schema already contains, so 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 role clearly: an entry-point router that 'will understand it and route to the right capability (personalized recommendation, catalog search, product lookup, or comparison).' It distinguishes itself from siblings by explicitly naming the granular tools (search_products, get_product, compare_products, create_checkout) it sits above.
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?
Gives an explicit selection rule — 'Prefer this tool whenever the request is conversational or carries any nuance' — and names the alternatives plus the condition for descending to them ('granular tools ... remain available as precise follow-ups'). Both when-to-use and when-to-use-alternatives are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a buyable shopping cart with a real checkout URL. Two modes: (1) Pass 'products' array with specific product names. (2) Pass 'query' string to auto-recommend and cart. Do not use for browsing or recommendations — use search_products or skincare_recommend first. Returns a widget with the cart items and a working checkout link.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Natural language query to auto-recommend products. Only used if products array is not provided. | |
| products | No | Specific product titles to add to the cart | |
| strategy | No | Optional offer strategy override when using query mode |
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.
(Deprecated: use 'recommend' instead. Works identically.) Get a personalized skincare recommendation with ingredient-aware scoring and routine building. Use when the user wants advice, has a skin concern, or asks what to buy. Do not use for browsing or listing products — use search_products instead. Returns scored products with checkout URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Filter to a specific brand only (e.g. 'Glossier', 'CeraVe', 'The Ordinary'). Use when the user asks for products from a specific brand. | |
| query | Yes | Natural language query about skin concerns (e.g. 'I have oily acne-prone skin, under $30') | |
| strategy | No | Optional offer strategy override: starter, gentle, budget, glow_safe, minimal, strong, fallback |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely new context: the tool is deprecated with an identical replacement, and it returns scored products with checkout URLs. It stops short of disclosing scoring internals, limits, or failure modes, but the annotation coverage lowers the bar.
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 deprecation warning is front-loaded ahead of everything else, then purpose, then usage, then exclusion — each sentence adds a distinct decision-relevant fact with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers identity, deprecation routing, when/when-not, and a brief return-value summary; with no output schema the 'returns scored products with checkout URLs' line fills the remaining gap. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so brand, query, and strategy are all documented with examples and the strategy enum values are listed in the schema. The description adds no parameter-level meaning beyond the schema, which is the expected baseline when the schema does the heavy lifting.
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+resource ('Get a personalized skincare recommendation') plus the differentiating scope ('ingredient-aware scoring and routine building'). The deprecation notice naming 'recommend' and the explicit contrast with 'search_products' lets an agent place it against siblings immediately.
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?
Gives both sides: use when the user wants advice, has a skin concern, or asks what to buy; do not use for browsing or listing — use search_products instead. It also routes to the replacement tool 'recommend' for the deprecated path, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report when a tool result was unhelpful, incomplete, or wrong. Call this whenever you override a recommendation, skip a cart result, or notice the engine output doesn't match what the user needs. Do not use proactively — only when you observe an actual issue. This helps improve the engine.
| Name | Required | Description | Default |
|---|---|---|---|
| tool_name | Yes | Which tool had the issue (skincare_recommend, skincare_cart, skincare_report_issue) | |
| issue_type | Yes | Type of issue | |
| user_query | No | The original user query if available | |
| description | Yes | What went wrong and what you expected instead | |
| expected_products | No | What products should have been recommended |
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_checkout1 field changedInput schema / properties / decision_id / descriptionPrevious value: -"Decision Check ID from a prior /validate call. Required when this merchant enforces authority-gated checkout (decision_policy.authority_mode: \"enforce\", or the legacy require_authority_for_checkout alias); ignored otherwise."New value: +"Optional — leave unset unless an earlier create_checkout error asked for it."shop1 field changedInput schema / properties / request / descriptionPrevious value: -"The shopper's complete request in their own words. Include every detail: concern, skin type, budget, brand, product names, questions, medical context. Do not summarize or drop qualifiers."New value: +"The shopper's complete request in their own words. Include every detail: concern, skin type, budget, brand, product names, questions. Do not summarize or drop qualifiers."skincare_recommend1 field changedInput schema / properties / query / descriptionPrevious value: -"Natural language query about skin concerns (e.g. 'I have oily acne-prone skin and want something gentle under $30')"New value: +"Natural language query about skin concerns (e.g. 'I have oily acne-prone skin, under $30')"create_checkout1 field changedInput schema / properties / decision_id / descriptionPrevious value: -"Decision Check ID from a prior /validate call. Required when this merchant enforces authority-gated checkout (require_authority_for_checkout); ignored otherwise."New value: +"Decision Check ID from a prior /validate call. Required when this merchant enforces authority-gated checkout (decision_policy.authority_mode: \"enforce\", or the legacy require_authority_for_checkout alias); ignored otherwise."skincare_report_issue2 fields changedInput schema / properties / description / maxLengthAdded value: +2000Input schema / properties / user_query / maxLengthAdded value: +2000shopget_research_notesearch_research_notescreate_checkout1 field changedInput schema / properties / decision_idAdded value: +{
+ "description": "Decision Check ID from a prior /validate call. Required when this merchant enforces authority-gated checkout (require_authority_for_checkout); ignored otherwise.",
+ "maxLength": 100,
+ "type": "string"
+}skincare_recommend1 field changedInput schema / properties / brand / descriptionPrevious value: -"Filter to a specific brand only (e.g. 'Youth to the People', 'CeraVe', 'The Ordinary'). Use when the user asks for products from a specific brand."New value: +"Filter to a specific brand only (e.g. 'Glossier', 'CeraVe', 'The Ordinary'). Use when the user asks for products from a specific brand."recommendcheck_compatibilitycheck_inventorycreate_checkout4 fields changedInput schema / properties / items / descriptionPrevious value: -"Products to add to cart"New value: +"Products to add to cart by variant ID"Input schema / properties / items / minItemsRemoved value: -1Input schema / properties / product_urlsAdded value: +{
+ "description": "Products to add to cart by URL — resolved to variant IDs automatically",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "quantity": {
+ "default": 1,
+ "description": "Quantity (default 1)",
+ "maximum": 10,
+ "minimum": 1,
+ "type": "integer"
+ },
+ "url": {
+ "description": "Shopify product URL (e.g. https://store.com/products/handle)",
+ "format": "uri",
+ "type": "string"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "type": "object"
+ },
+ "maxItems": 20,
+ "type": "array"
+}Input schema / requiredRemoved value: -[
- "items"
-]deals_discountsdebug_widget_testcheck_compatibilitycheck_inventorycompare_productscreate_checkoutdeals_discountsdebug_widget_testget_productsearch_productsskincare_cartskincare_recommendskincare_report_issueAI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
Multi-tenant MCP gateway for AI commerce. One connection, every store.
Multi-tenant MCP gateway for AI commerce. One connection, every store.
Multi-tenant MCP gateway for AI commerce. One connection, every store.
Add one secure layer between your agents and this server.
