Tool tree
search_catalogAnswer
Search the store catalog for products, collections, articles, and pages. Does NOT add anything to the cart; use create_cart or update_cart for cart changes. Each product carries variant_id, its selected or first available variant. If the user asks for a specific product variant, call get_product after search_catalog to get that variant's id, or use show_variant to display it.
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 create_cart or update_cart for cart changes. Each product carries variant_id, its selected or first available variant. If the user asks for a specific product variant, call get_product after search_catalog to get that variant's id, or use show_variant to display it.",
"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 create_cart or update_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 confirms the destination, and no further navigation is needed to show 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 create_cart or update_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 confirms the destination, and no further navigation is needed to show 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 a cart change — 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 create_cart or update_cart for that. To view a specific variant (color/size/etc.) in the browser, use show_variant instead — it accepts partial option selections like "purple" without needing every option. To add a specific variant to the cart, call get_product with catalog.selected_options to get its variant id. With catalog.navigate=true this MOVES the browser to the product page; the tool result confirms the destination, and no further navigation is needed to show 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 a cart change — 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 create_cart or update_cart for that. To view a specific variant (color/size/etc.) in the browser, use show_variant instead — it accepts partial option selections like \"purple\" without needing every option. To add a specific variant to the cart, call get_product with catalog.selected_options to get its variant id. With catalog.navigate=true this MOVES the browser to the product page; the tool result confirms the destination, and no further navigation is needed to show 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 create_cart or update_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 confirms the destination, and no further navigation is needed to show 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 create_cart or update_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 confirms the destination, and no further navigation is needed to show 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 shopper's current cart: its id, every line (line id, product and variant titles, variant id, handle, URL, image, unit price, quantity, line price) and the totals. Everything needed to describe the cart to the user in natural language, without a follow-up get_product call per line. It is also where a change to an existing cart starts from: update_cart takes the cart's id and the complete set of lines the cart should hold, and create_cart applies only to a cart with no items. Works from any page.
View tool JSON
{
"name": "get_cart",
"kind": "answer",
"impl": "imperative",
"description": "Get the shopper's current cart: its id, every line (line id, product and variant titles, variant id, handle, URL, image, unit price, quantity, line price) and the totals. Everything needed to describe the cart to the user in natural language, without a follow-up get_product call per line. It is also where a change to an existing cart starts from: update_cart takes the cart's id and the complete set of lines the cart should hold, and create_cart applies only to a cart with no items. Works from any page.",
"inputSchema": {
"type": "object",
"properties": {}
},
"page": "/"
}create_cartAction
Create the shopper's cart with the given items, for a shopper whose cart has no items yet. It is the tool for a shopper asking to add or buy something when the cart is empty, and that request is all the authorization it needs. Each line item names a ProductVariant GID in item.id (variant_id from search_catalog or browse_store, or variants[].id from get_product for specific options) and a quantity; every item from one request fits in one call. When the cart already has items, nothing is created or changed: the result is that existing cart with an error message, and update_cart can extend it with its current lines plus the new ones. Returns the whole resulting cart, including its id and line ids. Repeating a call with the same items leaves the cart as it is.
View tool JSON
{
"name": "create_cart",
"kind": "act",
"impl": "imperative",
"description": "Create the shopper's cart with the given items, for a shopper whose cart has no items yet. It is the tool for a shopper asking to add or buy something when the cart is empty, and that request is all the authorization it needs. Each line item names a ProductVariant GID in item.id (variant_id from search_catalog or browse_store, or variants[].id from get_product for specific options) and a quantity; every item from one request fits in one call. When the cart already has items, nothing is created or changed: the result is that existing cart with an error message, and update_cart can extend it with its current lines plus the new ones. Returns the whole resulting cart, including its id and line ids. Repeating a call with the same items leaves the cart as it is.",
"inputSchema": {
"type": "object",
"required": [
"cart"
],
"properties": {
"cart": {
"type": "object",
"required": [
"line_items"
],
"properties": {
"line_items": {
"type": "array",
"description": "The items the new cart holds.",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"item",
"quantity"
],
"properties": {
"item": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "ProductVariant GID, e.g. \"gid://shopify/ProductVariant/123\": variant_id from search_catalog or browse_store, variants[].id from get_product, or line_items[].item.id from a cart result."
}
}
},
"quantity": {
"type": "integer",
"description": "How many of this item the line holds.",
"minimum": 1
}
}
}
}
}
}
}
},
"page": "/"
}update_cartAction
Set the shopper's cart to exactly the given line items. This is a full replacement, not a patch: afterwards the cart holds these lines and only these. - A listed line with its line_items[].id keeps its place and is set to the given quantity, which is absolute (2 means 2, not 2 more). - A listed item without a line id is added, or, when that variant is already on one line of the cart, sets that line's quantity. - A line in the cart that is not listed is removed. It takes the cart's lines as most recently returned by get_cart, create_cart or update_cart. When the cart has changed since then (for example, the shopper edited it on the page, or a new cart replaced it), or an id is given that is not the shopper's current cart, nothing changes and the result is the current cart with an error message. Since the outcome depends only on the lines sent, repeating a call leaves the cart as it is. An empty line_items list empties the cart; leaving line_items out leaves the lines as they are. Returns the whole resulting cart, including its line ids, and messages about the call.
View tool JSON
{
"name": "update_cart",
"kind": "act",
"impl": "imperative",
"description": "Set the shopper's cart to exactly the given line items. This is a full replacement, not a patch: afterwards the cart holds these lines and only these.\n- A listed line with its line_items[].id keeps its place and is set to the given quantity, which is absolute (2 means 2, not 2 more).\n- A listed item without a line id is added, or, when that variant is already on one line of the cart, sets that line's quantity.\n- A line in the cart that is not listed is removed.\nIt takes the cart's lines as most recently returned by get_cart, create_cart or update_cart. When the cart has changed since then (for example, the shopper edited it on the page, or a new cart replaced it), or an id is given that is not the shopper's current cart, nothing changes and the result is the current cart with an error message. Since the outcome depends only on the lines sent, repeating a call leaves the cart as it is. An empty line_items list empties the cart; leaving line_items out leaves the lines as they are. Returns the whole resulting cart, including its line ids, and messages about the call.",
"inputSchema": {
"type": "object",
"required": [
"cart"
],
"properties": {
"id": {
"type": "string",
"description": "Optional: the page has one cart, the shopper's, and update_cart always acts on it. When given (the id from a cart result), it is compared with the current cart, and a mismatch changes nothing."
},
"cart": {
"type": "object",
"properties": {
"line_items": {
"type": "array",
"description": "The complete set of lines the cart holds afterwards. Empty empties the cart; absent leaves the lines as they are.",
"maxItems": 100,
"items": {
"type": "object",
"required": [
"item",
"quantity"
],
"properties": {
"id": {
"type": "string",
"description": "Existing cart line id (line_items[].id from a cart result). Absent for an item that is not in the cart yet."
},
"item": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "ProductVariant GID, e.g. \"gid://shopify/ProductVariant/123\": variant_id from search_catalog or browse_store, variants[].id from get_product, or line_items[].item.id from a cart result."
}
}
},
"quantity": {
"type": "integer",
"description": "How many of this item the line holds.",
"minimum": 1
}
}
}
}
}
}
}
},
"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 confirms the destination, and no further navigation is needed to show 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 confirms the destination, and no further navigation is needed to show 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 confirms the destination, and no further navigation is needed to show 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 confirms the destination, and no further navigation is needed to show it.",
"inputSchema": {
"type": "object",
"properties": {}
},
"page": "/"
}ask_businessAnswer
Ask the store a question about its policies and services: returns, refunds and exchanges, shipping and delivery, privacy, terms, subscriptions, contact details and opening hours, or FAQ topics such as gift wrapping. The store answers it: from its own knowledge base when the store offers Ask, otherwise from its published policies, FAQ pages and articles. Put the shopper's question in ask.query in their own words, one question per call; name the topic when the shopper only implies it (e.g. a question about sending back a gift is a returns question). Read-only: it does not change the cart, place orders, or start returns. For products, prices and availability, use search_catalog or get_product. Examples of questions: - What is your return policy? - How long does shipping to Canada take? - What is your phone number? - What are your hours of operation? - Do you offer gift wrapping?
View tool JSON
{
"name": "ask_business",
"kind": "answer",
"impl": "imperative",
"description": "Ask the store a question about its policies and services: returns, refunds and exchanges, shipping and delivery, privacy, terms, subscriptions, contact details and opening hours, or FAQ topics such as gift wrapping. The store answers it: from its own knowledge base when the store offers Ask, otherwise from its published policies, FAQ pages and articles. Put the shopper's question in ask.query in their own words, one question per call; name the topic when the shopper only implies it (e.g. a question about sending back a gift is a returns question). Read-only: it does not change the cart, place orders, or start returns. For products, prices and availability, use search_catalog or get_product.\nExamples of questions:\n - What is your return policy?\n - How long does shipping to Canada take?\n - What is your phone number?\n - What are your hours of operation?\n - Do you offer gift wrapping?\n",
"inputSchema": {
"type": "object",
"required": [
"ask"
],
"properties": {
"ask": {
"type": "object",
"description": "The question and optional buyer context.",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 10000,
"description": "The shopper's question, in natural language."
},
"context": {
"type": "object",
"description": "Optional buyer context, such as the shopper's country or language. Send only what the question needs.",
"additionalProperties": true,
"properties": {
"intent": {
"type": "string",
"description": "What the shopper is trying to do, when it adds to the question (e.g. \"returning a gift they received\")."
},
"address_country": {
"type": "string",
"description": "The buyer's country, e.g. \"US\"."
},
"address_region": {
"type": "string",
"description": "The buyer's state or region, e.g. \"CA\"."
},
"language": {
"type": "string",
"description": "The preferred language, e.g. \"en\"."
}
}
}
}
}
}
},
"page": "/"
}get_ucp_profileAnswer
Get this store's Universal Commerce Protocol (UCP) profile, as served at /.well-known/ucp: the UCP version, the services the store offers with their endpoints (e.g. the store's UCP MCP server), its capabilities, and its payment handlers. Use it to discover how to continue a purchase with this store over UCP, or to check which platform operates the store. Read-only; works from any page.
View tool JSON
{
"name": "get_ucp_profile",
"kind": "answer",
"impl": "imperative",
"description": "Get this store's Universal Commerce Protocol (UCP) profile, as served at /.well-known/ucp: the UCP version, the services the store offers with their endpoints (e.g. the store's UCP MCP server), its capabilities, and its payment handlers. Use it to discover how to continue a purchase with this store over UCP, or to check which platform operates the store. Read-only; works from any page.",
"inputSchema": {
"type": "object",
"properties": {}
},
"page": "/"
}