Apostle — AI Men's Skincare Commerce

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.

{
  "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#"
}

(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.

{
  "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#"
}

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).

{
  "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#"
}

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.

{
  "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#"
}

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.

{
  "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 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.

{
  "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 the summary and URL of a specific SearchShopAI Research Note by its slug (returned by search_research_notes).

{
  "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#"
}

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.

{
  "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 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.

{
  "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 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.

{
  "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 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.

{
  "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 (decision_policy.authority_mode: \"enforce\", or the legacy require_authority_for_checkout alias); ignored otherwise."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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?'

{
  "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 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.

{
  "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#"
}

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.

{
  "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#"
}