Tool tree
search_catalogAnswer
Search the store catalog for products, collections, articles, and pages. Does NOT add anything to the cart; use add_to_cart for cart changes. If the user asks for a specific product variant, call get_product after search_catalog to inspect available variants, then show_variant to display one.
View tool JSON
{
"name": "search_catalog",
"kind": "answer",
"impl": "imperative",
"description": "Search the store catalog for products, collections, articles, and pages. Does NOT add anything to the cart; use add_to_cart for cart changes. If the user asks for a specific product variant, call get_product after search_catalog to inspect available variants, then show_variant to display one.",
"inputSchema": {
"type": "object",
"required": [
"catalog"
],
"properties": {
"catalog": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Search query string."
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Max results per type (1-10). Defaults to 5.",
"default": 5,
"minimum": 1,
"maximum": 10
}
}
}
}
}
}
},
"page": "/"
}browse_storeAction
Browse OR navigate to store collections. Set navigate=true whenever the user wants to be taken to a collection page in the browser (triggers: "browse to", "go to", "show me", "open", "take me to", "navigate to" a collection or category). With navigate=false (default), returns collection or product data without changing the page — use this only when the user is asking a question about the catalog, not asking to view it. Without a collection handle, lists all collections. With a handle, returns products from that collection; use "all" to browse everything. Does NOT add anything to the cart; use add_to_cart for cart changes. Prefer this over search_catalog when the user names a category, collection, or wants to explore. With navigate=true this MOVES the browser to the collection page; the tool result then confirms the destination and instructs you not to navigate again — follow it.
View tool JSON
{
"name": "browse_store",
"kind": "act",
"impl": "imperative",
"description": "Browse OR navigate to store collections. Set navigate=true whenever the user wants to be taken to a collection page in the browser (triggers: \"browse to\", \"go to\", \"show me\", \"open\", \"take me to\", \"navigate to\" a collection or category). With navigate=false (default), returns collection or product data without changing the page — use this only when the user is asking a question about the catalog, not asking to view it. Without a collection handle, lists all collections. With a handle, returns products from that collection; use \"all\" to browse everything. Does NOT add anything to the cart; use add_to_cart for cart changes. Prefer this over search_catalog when the user names a category, collection, or wants to explore. With navigate=true this MOVES the browser to the collection page; the tool result then confirms the destination and instructs you not to navigate again — follow it.",
"inputSchema": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "Collection handle to browse (e.g. \"best-sellers\", \"new-arrivals\"). Omit to list all collections. Use \"all\" to browse every product."
},
"navigate": {
"type": "boolean",
"description": "When true, navigate the browser to the collection page after loading data. Set true for user intents like \"browse to\", \"go to\", \"show me\", \"open\", \"take me to\" a collection. Requires a collection handle. Defaults to false."
},
"sort_by": {
"type": "string",
"description": "Sort order. Options: best-selling (default), price-ascending, price-descending, title-ascending, title-descending, created-descending, created-ascending."
},
"page": {
"type": "number",
"description": "Page number for pagination (starts at 1). Each page returns up to 30 products."
}
}
},
"page": "/"
}get_productAnswer
Get product details, OR navigate the browser to the product page. Set catalog.navigate=true whenever the user wants to see/view the product in the browser (triggers: "show me", "open", "view", "go to", "take me to", "navigate to" a product). Set catalog.navigate=false (default) only when you need data (description, options, variants, prices, availability) to answer a question or to prepare an add_to_cart call — the browser stays on the current page. Defaults to the current page's product if no catalog.id is provided. Does NOT add anything to the cart; use add_to_cart for that. For a specific variant (color/size/etc.), use show_variant instead — it accepts partial option selections like "purple" without needing every option. With catalog.navigate=true this MOVES the browser to the product page; the tool result then confirms the destination and instructs you not to navigate again — follow it.
View tool JSON
{
"name": "get_product",
"kind": "answer",
"impl": "imperative",
"description": "Get product details, OR navigate the browser to the product page. Set catalog.navigate=true whenever the user wants to see/view the product in the browser (triggers: \"show me\", \"open\", \"view\", \"go to\", \"take me to\", \"navigate to\" a product). Set catalog.navigate=false (default) only when you need data (description, options, variants, prices, availability) to answer a question or to prepare an add_to_cart call — the browser stays on the current page. Defaults to the current page's product if no catalog.id is provided. Does NOT add anything to the cart; use add_to_cart for that. For a specific variant (color/size/etc.), use show_variant instead — it accepts partial option selections like \"purple\" without needing every option. With catalog.navigate=true this MOVES the browser to the product page; the tool result then confirms the destination and instructs you not to navigate again — follow it.",
"inputSchema": {
"type": "object",
"properties": {
"catalog": {
"type": "object",
"description": "Product detail parameters.",
"properties": {
"id": {
"type": "string",
"description": "Storefront API Product GID, product handle, or product URL path. Custom app product paths and Shopify standard /products/<handle> paths are supported. The id field from search_catalog or browse_store can be passed directly. If omitted, uses the current page's product."
},
"navigate": {
"type": "boolean",
"description": "When true, navigate the browser to the product page after fetching details. Set true for user intents like \"show me\", \"open\", \"view\", \"go to\", \"take me to\" a product. Defaults to false. If the user specified partial options (e.g. only a color), prefer show_variant with selected_options instead."
},
"selected_options": {
"type": "array",
"description": "Known product option selections to filter available_options. Use exact option names and values from search_catalog options or a prior get_product available_options entry.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Option name, e.g. \"Size\" or \"Color\"."
},
"value": {
"type": "string",
"description": "Option value, e.g. \"160cm\" or \"Fiberglass\"."
}
},
"required": [
"name",
"value"
]
}
}
}
}
}
},
"page": "/"
}show_variantAction
Navigate the browser to a product page, with a specific variant OR a partial option filter selected. Use for view intents: "show me", "open", "view", "go to", "take me to" a specific product configuration. Accepts EITHER variant_id (fully specified variant) OR selected_options (partial, e.g. only Color=Purple) — with partial options the first matching available variant is picked automatically, so DO NOT ask the user for missing options when their intent is to view. Does NOT add anything to the cart; use add_to_cart for cart changes. For cart operations you still need a full variant_id — call get_product with the full option combination first. This MOVES the browser to the exact variant page with the variant pre-selected; the tool result then confirms the destination and instructs you not to navigate again — follow it.
View tool JSON
{
"name": "show_variant",
"kind": "act",
"impl": "imperative",
"description": "Navigate the browser to a product page, with a specific variant OR a partial option filter selected. Use for view intents: \"show me\", \"open\", \"view\", \"go to\", \"take me to\" a specific product configuration. Accepts EITHER variant_id (fully specified variant) OR selected_options (partial, e.g. only Color=Purple) — with partial options the first matching available variant is picked automatically, so DO NOT ask the user for missing options when their intent is to view. Does NOT add anything to the cart; use add_to_cart for cart changes. For cart operations you still need a full variant_id — call get_product with the full option combination first. This MOVES the browser to the exact variant page with the variant pre-selected; the tool result then confirms the destination and instructs you not to navigate again — follow it.",
"inputSchema": {
"type": "object",
"required": [
"catalog"
],
"properties": {
"catalog": {
"type": "object",
"description": "Provide EITHER variant_id OR selected_options. Handle is required unless the user is already on the product page.",
"properties": {
"handle": {
"type": "string",
"description": "Product handle. If omitted, uses the current product page's handle."
},
"variant_id": {
"type": [
"string",
"number"
],
"description": "ProductVariant ID from get_product variants[].id, e.g. \"gid://shopify/ProductVariant/123\", or the numeric variant ID. Use when the user picked a specific fully-specified variant. Omit when using selected_options."
},
"selected_options": {
"type": "array",
"description": "Partial (or full) option selections, e.g. [{\"name\":\"Color\",\"value\":\"Purple\"}]. Use when the user names some options but not all (e.g. \"show me the purple shoe\" — pass only Color). The first matching available variant will be selected automatically. Use exact option names and values from get_product available_options or search_catalog options.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
}
}
}
},
"page": "/"
}get_cartAnswer
Get the current shopping cart contents — line items with product titles, variant titles, handles, URLs, images, unit prices, quantities, and totals. Everything needed to describe the cart to the user in natural language, without a follow-up get_product call per line. Works from any page.
View tool JSON
{
"name": "get_cart",
"kind": "answer",
"impl": "imperative",
"description": "Get the current shopping cart contents — line items with product titles, variant titles, handles, URLs, images, unit prices, quantities, and totals. Everything needed to describe the cart to the user in natural language, without a follow-up get_product call per line. Works from any page.",
"inputSchema": {
"type": "object",
"properties": {}
},
"page": "/"
}add_to_cartAction
Add products to the cart. Call this as soon as the user asks to ADD items (triggers: "add ... to my cart", "buy", "I'll take", "put ... in my basket") — in ONE call listing every item they named, up to the 10-entry limit. That request IS the authorization: do NOT ask the user to confirm before calling, and do NOT stop after search_catalog or get_product merely to report the variant you found — make the change, then tell the user it is done. Batch every item for ONE request into a SINGLE call — line_items accepts up to 10 entries; do NOT call add_to_cart once per item. Batching applies WITHIN a single request: each new thing the user asks for later is its own call. If one request names more than 10 items, split just that request into as few calls as possible. Do NOT retry a call that already returned a result: adds are cumulative, so repeating a call adds duplicate items. Use line_items[].item.id with a ProductVariant GID when the exact variant is known. Use handle or query only when adding the selected or first available variant. To change a quantity or remove something already in the cart, use update_cart_lines instead — this tool can only add.
View tool JSON
{
"name": "add_to_cart",
"kind": "act",
"impl": "imperative",
"description": "Add products to the cart. Call this as soon as the user asks to ADD items (triggers: \"add ... to my cart\", \"buy\", \"I'll take\", \"put ... in my basket\") — in ONE call listing every item they named, up to the 10-entry limit. That request IS the authorization: do NOT ask the user to confirm before calling, and do NOT stop after search_catalog or get_product merely to report the variant you found — make the change, then tell the user it is done. Batch every item for ONE request into a SINGLE call — line_items accepts up to 10 entries; do NOT call add_to_cart once per item. Batching applies WITHIN a single request: each new thing the user asks for later is its own call. If one request names more than 10 items, split just that request into as few calls as possible. Do NOT retry a call that already returned a result: adds are cumulative, so repeating a call adds duplicate items. Use line_items[].item.id with a ProductVariant GID when the exact variant is known. Use handle or query only when adding the selected or first available variant. To change a quantity or remove something already in the cart, use update_cart_lines instead — this tool can only add.",
"inputSchema": {
"type": "object",
"required": [
"cart"
],
"properties": {
"cart": {
"type": "object",
"required": [
"line_items"
],
"properties": {
"line_items": {
"type": "array",
"description": "Items to add (1-10).",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"item": {
"type": "object",
"description": "The merchandise to add.",
"properties": {
"id": {
"type": "string",
"description": "ProductVariant GID from get_product variants[].id, e.g. \"gid://shopify/ProductVariant/123\"."
}
}
},
"handle": {
"type": "string",
"description": "Product handle. Adds the selected or first available variant; call get_product first if the user requested specific options."
},
"query": {
"type": "string",
"description": "Search query to find and add the selected or first available variant. For specific variants, call search_catalog/get_product first and pass item.id."
},
"quantity": {
"type": "integer",
"description": "How many to add. Defaults to 1.",
"minimum": 1,
"default": 1
}
}
}
}
}
}
}
},
"page": "/"
}update_cart_linesAction
Change the quantity of items already in the cart, or remove them. Every change here addresses an existing cart line by its id, so call get_cart first unless you already have line_items[].id from an earlier get_cart in this conversation. Pass the ABSOLUTE target quantity, not a delta — quantity 2 means the line ends up at 2 regardless of what it was. Use quantity 0 to remove the line entirely. Batch every change for ONE request into a SINGLE call — line_items accepts up to 10 entries; do NOT call update_cart_lines once per line. Batching applies WITHIN a single request: each new thing the user asks for later is its own call. This tool cannot add new merchandise. To add something not already in the cart, use add_to_cart. To empty the whole cart at once, use cancel_cart.
View tool JSON
{
"name": "update_cart_lines",
"kind": "act",
"impl": "imperative",
"description": "Change the quantity of items already in the cart, or remove them. Every change here addresses an existing cart line by its id, so call get_cart first unless you already have line_items[].id from an earlier get_cart in this conversation. Pass the ABSOLUTE target quantity, not a delta — quantity 2 means the line ends up at 2 regardless of what it was. Use quantity 0 to remove the line entirely. Batch every change for ONE request into a SINGLE call — line_items accepts up to 10 entries; do NOT call update_cart_lines once per line. Batching applies WITHIN a single request: each new thing the user asks for later is its own call. This tool cannot add new merchandise. To add something not already in the cart, use add_to_cart. To empty the whole cart at once, use cancel_cart.",
"inputSchema": {
"type": "object",
"required": [
"cart"
],
"properties": {
"cart": {
"type": "object",
"required": [
"line_items"
],
"properties": {
"line_items": {
"type": "array",
"description": "Existing cart lines to update or remove (1-10).",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"required": [
"id",
"quantity"
],
"properties": {
"id": {
"type": "string",
"description": "Existing cart line id from get_cart line_items[].id. Required — this tool cannot resolve products by name."
},
"quantity": {
"type": "integer",
"description": "Absolute target quantity for this line (not a delta). 0 removes the line.",
"minimum": 0
}
}
}
}
}
}
}
},
"page": "/"
}cancel_cartAction
Remove all items from the cart in one step. Use when the user wants to empty their cart or start over.
View tool JSON
{
"name": "cancel_cart",
"kind": "act",
"impl": "imperative",
"description": "Remove all items from the cart in one step. Use when the user wants to empty their cart or start over.",
"inputSchema": {
"type": "object",
"properties": {}
},
"page": "/"
}proceed_to_checkoutAction
Proceed to checkout. Verifies the cart is not empty, then MOVES the browser to the checkout page. The tool result then confirms the destination and instructs you not to navigate again — follow it.
View tool JSON
{
"name": "proceed_to_checkout",
"kind": "act",
"impl": "imperative",
"description": "Proceed to checkout. Verifies the cart is not empty, then MOVES the browser to the checkout page. The tool result then confirms the destination and instructs you not to navigate again — follow it.",
"inputSchema": {
"type": "object",
"properties": {}
},
"page": "/"
}manage_ordersAction
Navigate to the customer's order history page. Use when the user asks about past orders, order status, tracking, or returns. The user will be prompted to log in if not already authenticated. This MOVES the browser to the order history page; the tool result then confirms the destination and instructs you not to navigate again — follow it.
View tool JSON
{
"name": "manage_orders",
"kind": "act",
"impl": "imperative",
"description": "Navigate to the customer's order history page. Use when the user asks about past orders, order status, tracking, or returns. The user will be prompted to log in if not already authenticated. This MOVES the browser to the order history page; the tool result then confirms the destination and instructs you not to navigate again — follow it.",
"inputSchema": {
"type": "object",
"properties": {}
},
"page": "/"
}search_shop_policies_and_faqsAnswer
Used to get facts about the store's policies, FAQ, or contact details. When the question is about specific policy kinds, set policy_types to those kinds; leave it unset for general FAQ questions. Some examples of questions you can ask are: - What is your return policy? (policy_types: ["refund"]) - What is your shipping policy? (policy_types: ["shipping"]) - What is your phone number? (policy_types: ["contact"]) - What are your hours of operation? (policy_types: ["contact"]) - Do you offer gift wrapping? (general FAQ, no specific policy kind — leave policy_types unset)
View tool JSON
{
"name": "search_shop_policies_and_faqs",
"kind": "answer",
"impl": "imperative",
"description": "Used to get facts about the store's policies, FAQ, or contact details.\nWhen the question is about specific policy kinds, set policy_types to those kinds; leave it unset for general FAQ questions.\nSome examples of questions you can ask are:\n - What is your return policy? (policy_types: [\"refund\"])\n - What is your shipping policy? (policy_types: [\"shipping\"])\n - What is your phone number? (policy_types: [\"contact\"])\n - What are your hours of operation? (policy_types: [\"contact\"])\n - Do you offer gift wrapping? (general FAQ, no specific policy kind — leave policy_types unset)\n",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "A natural language query. Searches FAQ pages and articles, and routes policies by keyword when policy_types is omitted."
},
"policy_types": {
"type": "array",
"description": "Policy kinds to fetch, chosen from the user's question — e.g. [\"refund\"] for returns/exchanges, [\"contact\"] for phone/hours/address. Include every kind the question touches. Omit when no specific policy is relevant (e.g. a general FAQ question).",
"items": {
"type": "string",
"enum": [
"refund",
"shipping",
"privacy",
"terms_of_service",
"terms_of_sale",
"subscription",
"legal_notice",
"contact"
]
}
}
},
"required": [
"query"
]
},
"page": "/"
}