shop

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, medical context. 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.

Parameters5

request	string	required	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.
intent	string	optional	Secondary hint only — the primary signal is `request`.
budget_max	number	optional	Secondary hint only — maximum budget if stated.
brand	string	optional	Secondary hint only — brand filter if stated.
product_refs	array	optional	Secondary hint only — exact product titles/SKUs when already known.

Raw schema

{
  "type": "object",
  "properties": {
    "request": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "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."
    },
    "intent": {
      "type": "string",
      "enum": [
        "advice",
        "browse",
        "product",
        "compare",
        "buy",
        "question"
      ],
      "description": "Secondary hint only — the primary signal is `request`."
    },
    "budget_max": {
      "type": "number",
      "description": "Secondary hint only — maximum budget if stated."
    },
    "brand": {
      "type": "string",
      "maxLength": 100,
      "description": "Secondary hint only — brand filter if stated."
    },
    "product_refs": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200
      },
      "maxItems": 5,
      "description": "Secondary hint only — exact product titles/SKUs when already known."
    }
  },
  "required": [
    "request"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

skincare_recommend

(Deprecated: use 'recommend' instead. Works identically.) Get a personalized Apostle product recommendation with ingredient-aware scoring, safety notes, and routine building. Use when the user wants advice on what to buy, needs help choosing between products, has a specific skin concern (acne, aging, dryness, sensitivity, etc.), wants a routine, or asks "what should I use for X." Do not use for browsing or listing products — use search_products instead. Returns scored products with explanations, usage instructions, and Shopify checkout. This tool analyzes ingredients, irritation risk, and product compatibility — use it over search_products when the user needs guidance, not just a product list.

Parameters3

query	string	required	Natural language query about skin concerns (e.g. 'I have oily acne-prone skin and want something gentle under $30')
strategy	string	optional	Optional offer strategy override: starter, gentle, budget, glow_safe, minimal, strong, fallback
brand	string	optional	Filter to a specific brand only (e.g. 'Glossier', 'CeraVe', 'The Ordinary'). Use when the user asks for products from a specific brand.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 2000,
      "description": "Natural language query about skin concerns (e.g. 'I have oily acne-prone skin and want something gentle under $30')"
    },
    "strategy": {
      "type": "string",
      "maxLength": 50,
      "description": "Optional offer strategy override: starter, gentle, budget, glow_safe, minimal, strong, fallback"
    },
    "brand": {
      "type": "string",
      "maxLength": 100,
      "description": "Filter to a specific brand only (e.g. 'Glossier', 'CeraVe', 'The Ordinary'). Use when the user asks for products from a specific brand."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

recommend

Get a personalized product recommendation with domain-expert scoring, safety notes, and transaction authority. Use when the user wants advice, has a concern, or asks what to buy. Returns scored products with checkout URLs, safety assessment, and authority state (SHOULD/CAN/SHOULDNT/ESCALATE/CANT).

Parameters4

query	string	required	Natural language query about product needs
strategy	string	optional	Optional offer strategy override
brand	string	optional	Filter to a specific brand
domain	string	optional	Product domain (e.g. 'skincare', 'beauty_devices'). Auto-detected from merchant if omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 2000,
      "description": "Natural language query about product needs"
    },
    "strategy": {
      "type": "string",
      "maxLength": 50,
      "description": "Optional offer strategy override"
    },
    "brand": {
      "type": "string",
      "maxLength": 100,
      "description": "Filter to a specific brand"
    },
    "domain": {
      "type": "string",
      "maxLength": 50,
      "description": "Product domain (e.g. 'skincare', 'beauty_devices'). Auto-detected from merchant if omitted."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

skincare_cart

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.

Parameters3

products	array	optional	Specific product titles to add to the cart
query	string	optional	Natural language query to auto-recommend products. Only used if products array is not provided.
strategy	string	optional	Optional offer strategy override when using query mode

Raw schema

{
  "type": "object",
  "properties": {
    "products": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200
      },
      "maxItems": 20,
      "description": "Specific product titles to add to the cart"
    },
    "query": {
      "type": "string",
      "maxLength": 2000,
      "description": "Natural language query to auto-recommend products. Only used if products array is not provided."
    },
    "strategy": {
      "type": "string",
      "maxLength": 50,
      "description": "Optional offer strategy override when using query mode"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

skincare_report_issue

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.

Parameters5

tool_name	string	required	Which tool had the issue (skincare_recommend, skincare_cart, skincare_report_issue)
issue_type	string	required	Type of issue
description	string	required	What went wrong and what you expected instead
user_query	string	optional	The original user query if available
expected_products	array	optional	What products should have been recommended

Raw schema

{
  "type": "object",
  "properties": {
    "tool_name": {
      "type": "string",
      "maxLength": 100,
      "description": "Which tool had the issue (skincare_recommend, skincare_cart, skincare_report_issue)"
    },
    "issue_type": {
      "type": "string",
      "enum": [
        "wrong_products",
        "too_few_products",
        "too_expensive",
        "ignored_concern",
        "ignored_budget",
        "bad_recommendation",
        "cart_mismatch",
        "missing_product",
        "other"
      ],
      "description": "Type of issue"
    },
    "description": {
      "type": "string",
      "maxLength": 2000,
      "description": "What went wrong and what you expected instead"
    },
    "user_query": {
      "type": "string",
      "maxLength": 2000,
      "description": "The original user query if available"
    },
    "expected_products": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "What products should have been recommended"
    }
  },
  "required": [
    "tool_name",
    "issue_type",
    "description"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_research_notes

Search SearchShop AI'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 SearchShop AI has written or published about a topic.

Parameters1

query

string

required

Topic or keywords, e.g. 'attribution', 'MCP', 'hallucinated prices'

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 200,
      "description": "Topic or keywords, e.g. 'attribution', 'MCP', 'hallucinated prices'"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_research_note

Get the summary and URL of a specific SearchShop AI Research Note by its slug (returned by search_research_notes).

Parameters1

slug

string

required

The note slug, e.g. 'the-ai-attribution-blind-spot'

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "maxLength": 120,
      "description": "The note slug, e.g. 'the-ai-attribution-blind-spot'"
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_products

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.

Parameters4

query	string	required	Search query (e.g. 'vitamin c serum', 'anti-aging', 'moisturizer under $50')
max_results	integer	optional	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.
max_price	number	optional	Filter to products at or below this price
category	string	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 500,
      "description": "Search query (e.g. 'vitamin c serum', 'anti-aging', 'moisturizer under $50')"
    },
    "max_results": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "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."
    },
    "max_price": {
      "type": "number",
      "description": "Filter to products at or below this price"
    },
    "category": {
      "type": "string",
      "description": "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."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_product

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.

Parameters2

sku	string	optional	Exact product SKU (e.g. 'LL-4632379916336')
title	string	optional	Product title to search for (fuzzy match)

Raw schema

{
  "type": "object",
  "properties": {
    "sku": {
      "type": "string",
      "description": "Exact product SKU (e.g. 'LL-4632379916336')"
    },
    "title": {
      "type": "string",
      "description": "Product title to search for (fuzzy match)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

compare_products

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.

Parameters1

products

array

required

Product titles or SKUs to compare (e.g. ['MIRA', 'CryoSculpt'])

Raw schema

{
  "type": "object",
  "properties": {
    "products": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200
      },
      "minItems": 2,
      "maxItems": 5,
      "description": "Product titles or SKUs to compare (e.g. ['MIRA', 'CryoSculpt'])"
    }
  },
  "required": [
    "products"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_checkout

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.

Parameters5

items	array	optional	Products to add to cart by variant ID
product_urls	array	optional	Products to add to cart by URL — resolved to variant IDs automatically
discount_code	string	optional	Discount code to apply (e.g. 'WELCOME10')
note	string	optional	Cart note visible to the merchant
decision_id	string	optional	Decision Check ID from a prior /validate call. Required when this merchant enforces authority-gated checkout (require_authority_for_checkout); ignored otherwise.

Raw schema

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "variant_id": {
            "type": [
              "string",
              "number"
            ],
            "description": "Shopify variant ID (numeric or GID format)"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1,
            "description": "Quantity (default 1)"
          },
          "selling_plan_id": {
            "type": "string",
            "description": "Shopify selling plan ID for subscriptions"
          }
        },
        "required": [
          "variant_id"
        ],
        "additionalProperties": false
      },
      "maxItems": 20,
      "description": "Products to add to cart by variant ID"
    },
    "product_urls": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Shopify product URL (e.g. https://store.com/products/handle)"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1,
            "description": "Quantity (default 1)"
          }
        },
        "required": [
          "url"
        ],
        "additionalProperties": false
      },
      "maxItems": 20,
      "description": "Products to add to cart by URL — resolved to variant IDs automatically"
    },
    "discount_code": {
      "type": "string",
      "maxLength": 50,
      "description": "Discount code to apply (e.g. 'WELCOME10')"
    },
    "note": {
      "type": "string",
      "maxLength": 500,
      "description": "Cart note visible to the merchant"
    },
    "decision_id": {
      "type": "string",
      "maxLength": 100,
      "description": "Decision Check ID from a prior /validate call. Required when this merchant enforces authority-gated checkout (require_authority_for_checkout); ignored otherwise."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_compatibility

Check which products are compatible with a given product. For devices, shows required consumables (e.g., conductive gel for MIRA). For topicals, shows which devices they work with. Use when a customer asks 'what gel do I need with MIRA?' or 'does this serum work with CryoSculpt?'

Parameters1

product

string

required

Product name or SKU to check compatibility for

Raw schema

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "maxLength": 200,
      "description": "Product name or SKU to check compatibility for"
    }
  },
  "required": [
    "product"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_inventory

Check if a product is currently available. Uses Shopify Storefront API to verify real-time stock status. Use when a customer asks 'is MIRA in stock?' or before recommending a product.

Parameters1

product

string

required

Product name or SKU to check availability for

Raw schema

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "maxLength": 200,
      "description": "Product name or SKU to check availability for"
    }
  },
  "required": [
    "product"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

deals_discounts

Show available bundles, deals, and ask about discount codes. Use when a customer asks about deals, bundles, savings, or says 'do you have any discounts?' Also use when multiple items are in cart to suggest bundle savings. Always ask if the customer has a discount code.

Parameters1

discount_code

string

optional

Customer's discount code if they have one

Raw schema

{
  "type": "object",
  "properties": {
    "discount_code": {
      "type": "string",
      "maxLength": 50,
      "description": "Customer's discount code if they have one"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Apostle — AI Men's Skincare Commerce

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

shop

skincare_recommend

recommend

skincare_cart

skincare_report_issue

search_research_notes

get_research_note

search_products

get_product

compare_products

create_checkout

check_compatibility

check_inventory

deals_discounts

Install

Remote endpoint