add_to_cart
ChatGPTAdd a product to the shopping cart. IMPORTANT: productId must be the id field from product-search results. If cartId is omitted, a new cart is created — its ID is returned in the response. Pass this cartId to all subsequent cart operations. A cartId the store does not know → errorCode CART_NOT_FOUND; a productId from another store → PRODUCT_NOT_FOUND. If the store accepts fewer units than requested the response carries requestedQuantity / appliedQuantity / reason; lineQuantity is what the line now holds. Each product is capped per order at the store's purchase limit (else stock, else 25): over it → MAX_UNITS_PER_ITEM_EXCEEDED with limit. A product the store does not sell online → NOT_SELLABLE_ONLINE. A non-integer or < 1 quantity → VALIDATION. One store: merchants: "<key>" + top-level fields; several: merchant_args: { "<key>": { ...fields } }. Flat cart: cart.lines[], subtotal, total; rupees (amountUnit:'major'). cartId optional with Mcp-Session-Id.
clear_cart
ChatGPTRemove all items from the cart. One store: merchants: "<key>" + top-level fields; several: merchant_args: { "<key>": { ...fields } }. cartId optional with Mcp-Session-Id.
create_checkout
ChatGPTCreate a REAL, payable Razorpay order and return a hosted checkout_url. Call once, after the shopper agrees. Args: { cartId } (from add_to_cart, full id incl. ?key=) OR { cartItems: [{productId|variantId, quantity}] }; optional pincode (6 digits, delivery check), idempotencyKey (8-128 chars; same key returns the same order). Reuse: a repeat on the same unchanged cart (or key) within 15 minutes returns that order with reused:true; a changed cart, or a call after that, mints a new order. Razorpay cannot cancel an unpaid order. total_amount is paise (total_amount_unit:'minor'); amount_display is human. Swiggy/Instamart/Dineout place real orders: without the shopper's yes they return CONSENT_REQUIRED; ask, then resend with notes.paymentMethod:'upi'. Error codes: see the usage guide. One store: merchants: "<key>" + top-level fields; several: merchant_args: { "<key>": { ...fields } }. checkout_url valid until expires_at or a cart change; several stores: report each of checkout.orders[] / failed[]. cartId optional with Mcp-Session-Id.
get_filter_options
ChatGPTGet the filter values (categories, brands, tags, sizes, colors, price range) valid for a product query at the store. Call it with the shopper's query before search_products when they mention a brand, category, size, color or other attribute. WORKFLOW: 1. User mentions a filter (brand/category/size/color/tags) — call this tool first, with query. 2. Use the exact value strings from the response. 3. Call search_products with the same query and those exact filter values. 4. Always follow this tool with a search_products call — never stop here. RETURNS (facets are computed from the products matching query; basedOn.sampleSize says how many): - productTypes: [{label, value, count}] — pass value as search_products.productType - vendors: [{label, value, count}] — pass value as search_products.vendor - tags: [{label, value, count}] — pass value in search_products.tags - priceRange: {min, max, currency} or null when unknown - variantOptions: [{name, values: [{value, count}]}] — e.g. {name: 'Size', values: [{value: 'M'}]} EXAMPLES: 'show me nike shoes' → get_filter_options({query: 'shoes'}), then search_products({query: 'shoes', vendor: 'Nike'}) 'blue t-shirts on sale' → get_filter_options({query: 't-shirts'}), then search_products({query: 't-shirts', tags: ['sale'], variantOptions: [{name: 'Color', value: 'Blue'}]}) Multi-store: omit merchants to auto-select stores; pass key(s) only when the shopper names a store. Results under merchants.<key>; those keys are the store keys for cart/checkout.
get_order_status
ChatGPTGet payment status for a Razorpay order. Pass razorpay_order_id (the order_id returned by create_checkout, 'order_' + 14 letters/digits). Returns found:true with order_status, payment_status (paid/pending), amount / amount_paid / amount_due in rupees (amountUnit:'major'; *_paise in paise), currency, payments and line_items [{name, quantity, unit_price, line_total}] in rupees (filled for Magic Checkout orders, which create_checkout makes; else [] with line_items_note); found:false with errorCode NOT_FOUND for an id this store does not own, or VALIDATION for a malformed id. It does NOT return the shipping address or fulfillment/shipment status. One store: merchants: "<key>" + top-level fields; several: merchant_args: { "<key>": { ...fields } }.
get_product_details
ChatGPTShow detailed information for a specific product. Use this tool when the user wants to see more details about a single product, view product images, or check available variants (sizes, colors). Pass the id from search results as productId (Shopify: a Product or ProductVariant gid, or the handle; Fynd: the numeric id or the slug). Returns price, compareAtPrice, currency, brand, url, inStock, variants[] and a plain-text return policy; serviceability only with pincode, sizePrice only with variantId. An unknown id returns errorCode PRODUCT_NOT_FOUND. One store: merchants: "<key>" + top-level fields; several: merchant_args: { "<key>": { ...fields } }.
list_merchants
ChatGPTList the stores this server can search, a page at a time. Returns key, storeName, platform, what the store sells, and health ('healthy' = answered recently, 'unknown' = not checked yet, 'degraded', or 'open' when the store is being skipped, with reason and retryAfter). Filter with platform, category (e.g. 'skin care', 'smartwatches') and health; page with limit and the returned nextCursor. Use key as the store key for merchants and merchant_args on every other tool. Stores that cannot be routed to are not listed.
remove_from_cart
ChatGPTRemove a product from the cart. Args: {cartId, productId | lineId, quantity?}. Without quantity the whole line is removed; with quantity it is reduced by that many (the line goes when it reaches 0). Identify the line by productId (variant id from search) OR lineId (from view_cart). Unknown cart → errorCode CART_NOT_FOUND; line not in cart → LINE_NOT_FOUND. One store: merchants: "<key>" + top-level fields; several: merchant_args: { "<key>": { ...fields } }. cartId optional with Mcp-Session-Id.
search_products
ChatGPTPrimary tool for showing products to users. Use this tool when the user wants to find, browse, search, or see products. Returns product results as plain text and structured data. SEARCH BEHAVIOR (matches Shopify website): - Full-text search across title, description, tags, AND variant option values (Color, Size, etc.) - Color/size keywords in query are auto-extracted to variantOptions for facet filtering - Example: 'blue tshirt' → query='tshirt' + variantOptions=[{name:'Color', value:'Blue'}] - Each store's result includes availableFilters (top category, brand, tag and option values, price range); call get_filter_options for the full lists FILTER USAGE RULES: 1. Apply every filter the user mentions: price, brand, category, size, color, or other attributes. 2. For price filters: extract numbers from user input (e.g., 'under 20000' → maxPrice: 20000). 3. For brand/category/tag/variant filters: call get_filter_options first to get valid values. EXAMPLES: - 'phones under 20000' → {query: 'phones', maxPrice: 20000} - 'nike shoes size 10' → call get_filter_options, then {query: 'nike shoes size 10'} — auto-extracts Size:10 - 'blue jeans 2000 to 5000' → call get_filter_options, then {query: 'blue jeans', minPrice: 2000, maxPrice: 5000} PHONE NUMBERS (recharge): put the digits in query, e.g. {query: '9876543210 long validity'}; there is no phone field. Multi-store: omit merchants to auto-select stores; pass key(s) only when the shopper names a store. Results under merchants.<key>; those keys are the store keys for cart/checkout.
update_cart_item
ChatGPTSet the absolute quantity of one cart line. Args: {cartId, productId | lineId, quantity}; quantity 0 removes. If the store accepts fewer units (purchase limit / stock) the response is still success:true and carries requestedQuantity, appliedQuantity and reason — tell the shopper the applied quantity. Above the product's per-order cap (store purchase limit, else stock, else 25) → MAX_UNITS_PER_ITEM_EXCEEDED with limit, nothing changed. One store: merchants: "<key>" + top-level fields; several: merchant_args: { "<key>": { ...fields } }. cartId optional with Mcp-Session-Id.
view_cart
ChatGPTRetrieve current cart contents, including items and quantities. Args: {cartId}. An unknown cartId returns success:false with errorCode CART_NOT_FOUND (an empty cart is success:true with no lines). Pass pincode (Shopify) or areaCode (Fynd), a 6-digit Indian pincode, to also check delivery for all items; serviceable:null means it could not be checked. Read-only: the cart is never changed. One store: merchants: "<key>" + top-level fields; several: merchant_args: { "<key>": { ...fields } }. Flat cart: cart.lines[], subtotal, total; rupees (amountUnit:'major'). cartId optional with Mcp-Session-Id.
