💬Get free consultation

MCP tool reference

How to read this page

Chatty exposes 17 tools. Eight are always registered. Nine depend on a switch in your AI agent settings, read fresh on every request. Your bot should call tools/list after connecting rather than trusting any list, including this one.

Every tool returns MCP text content: one content entry of type: "text". Most tools put a JSON object in that text, so parse it. A few return plain prose when there is nothing to report — No products found., No results found., No test conversations found., No team members found.. A tool that fails returns 200 with {"error": "..."} inside the text, not a protocol error.

---

Tools at a glance

Tool	What it does	Changes anything?	Switch that registers it	Plan needed for the switch
send_message	Posts a bot reply into a conversation.	Yes, and the customer sees it	Always on	All
faq_retrieval	Searches your knowledge base.	No	Always on	All
add_note	Adds an internal note to a conversation.	Yes	Always on	All
update_tags	Replaces the tags on a conversation.	Yes, replaces the whole list	Always on	All
assign_member	Assigns or unassigns a team member.	Yes	Always on	All
list_members	Lists team members and their ids.	No	Always on	All
list_conversations	Lists test conversations from the AI playground.	No	Always on	All
register_webhook	Creates a webhook subscription and returns its signing secret.	Yes	Always on	All
product_lookup	Searches products and variants.	No	Training data > Products	All
product_faq_lookup	Returns FAQs for one product.	No	Training data > Products	All
manage_cart	Reads and edits the Shopify cart.	Yes, except action: "get"	Training data > Products	All
collection_lookup	Searches collections and categories.	No	Training data > Collections	All
discount_lookup	Finds discounts and promo codes.	No	Training data > Discounts	All
size_guide_lookup	Returns a size chart for one product.	No	Assistant skills > Size guide	Pro
check_order_status	Tracks an order by order number or tracking number.	No	Assistant skills > Order tracking	Basic
customer_support	Runs an after-sale request: return, refund, cancel, edit.	No	Assistant skills > After-sale support	All
human_agent_transfer	Hands the conversation to a person.	No	Assistant skills > Human handover	All

customer_support and human_agent_transfer return a reply for your bot to send. Nothing reaches the customer until you call send_message.

---

Identifiers

Most tools need an id that only another tool can give you. Copy it exactly as Chatty returned it — never build, shorten, or reformat one.

Identifier	Shape	Where you get it
convoId	Opaque. Two shapes are in use: an all-digit id, and a 20-character mixed-case id. Both are valid, so do not normalize either.	The webhook payload, the X-Chatty-Convo-Id header, or GET /chat/conversations.
memberId	Opaque string.	list_members.
productId	gid://shopify/Product/<digits>	product_lookup. Needed by product_faq_lookup and size_guide_lookup.
variantId	gid://shopify/ProductVariant/<digits>	The variants array in a product_lookup result. Preferred for manage_cart add.
cartId	The Shopify cart id, passed through untouched.	Any manage_cart call. Required for get, update, and remove.
lineItemId	gid://shopify/CartLine/<uuid>?cart=<token>	manage_cart with action: "get". Required for update and remove. The ?cart= part belongs to the id — drop it and the id is rejected.
Webhook secret	whsec_ followed by 48 hex characters.	register_webhook, once.

---

Always available

These eight are registered for every store, on every plan that can hold an API key.

send_message

Sends a bot message to a conversation. Call it after composing your answer.

Parameter	Type	Required	Description
convoId	string	Yes	The conversation to post into. Must belong to the store the key belongs to.
text	string	Yes	The message body.
topic	string	No	Topic classification, for example Product inquiry or Order status. Defaults to General inquiry.

Returns { "messageId": "...", "convoId": "...", "saved": true }. The message is stored as an automated bot message. Errors: Conversation <id> not found, Conversation does not belong to this shop.

faq_retrieval

Searches your store's knowledge base: FAQs, scenarios, pages, and files.

Parameter	Type	Required	Description
query	string	Yes	The search text.

Returns an object with scenarios, faqs, pages, files, and any products those entries link to. Returns the text No results found. when nothing matches.

add_note

Adds an internal note to a conversation. Notes are visible to your team only, never to the customer.

Parameter	Type	Required	Description
convoId	string	No	The conversation. Falls back to the X-Chatty-Convo-Id header. One of the two must be present.
text	string	Yes	The note body. Whitespace is trimmed.

Returns { "noteId": "...", "convoId": "...", "saved": true }.

update_tags

Sets tags on a conversation. This replaces the existing tags — it does not merge. Read the current tags first if you mean to add one.

Parameter	Type	Required	Description
convoId	string	No	The conversation. Falls back to the X-Chatty-Convo-Id header.
tags	string[]	Yes	The full tag list. Each entry is trimmed and truncated to 50 characters, with no error when a tag is shortened. Empty entries are dropped, duplicates are removed, and only the first 100 tags are kept. Tags that do not exist yet are created.

Returns { "convoId": "...", "tags": ["..."], "saved": true }. An all-empty list returns {"error": "No valid tags provided"}.

assign_member

Assigns a team member to a conversation, or unassigns.

Parameter	Type	Required	Description
convoId	string	No	The conversation. Falls back to the X-Chatty-Convo-Id header.
memberId	string	No	The member to assign. Takes priority over email.
email	string	No	The member's email, as an alternative to memberId.

Omit both memberId and email to unassign.

Returns { "convoId": "...", "memberId": "...", "memberName": "...", "assigned": true } when assigning, or { "convoId": "...", "memberId": null, "unassigned": true } when clearing. Errors: Member not found, Member is not active, Member does not belong to this shop.

list_members

Lists team members for your store. Use it to find member ids before assigning.

Takes no parameters.

Returns { "members": [ { "id", "email", "firstName", "lastName", "fullName", "role", "active" } ] }. Returns the text No team members found. when the store has none.

list_conversations

Lists test conversations, with cursor pagination.

Parameter	Type	Required	Description
limit	number	No	Conversations per page. Default 20, and there is no maximum — whatever number you pass is what the query returns, so keep it to a size your client can handle.
after	string	No	Conversation id cursor. Fetches the page after this one.
before	string	No	Conversation id cursor. Fetches the page before this one.
sort	string	No	Field and direction, for example updatedAt_desc or createdAt_asc. Default updatedAt_desc.
search	string	No	Matches on conversation id.

Returns a formatted text list, not JSON: one line per conversation with its id, updatedAt, and the first 100 characters of the last message, followed by a pagination line naming the before and after values to use next.

register_webhook

Registers a webhook subscription and returns its signing secret.

Parameter	Type	Required	Description
url	string	Yes	The HTTPS URL that receives deliveries.
events	string[]	Yes	Event names. Valid values: message.created, message.updated, message.removed, conversation.created, conversation.state_changed, conversation.assigned, conversation.tags_updated, conversation.removed, customer.created.

Returns { "subscriptionId": "...", "url": "...", "events": [...], "secret": "whsec_...", "active": true }.

---

Registered by Training data > Products

One switch registers all three. Turning on AI agent > Training data > Products gives your bot product search, product FAQs, and full cart write access at the same time. There is no separate cart switch. This switch is off by default.

product_lookup

Searches products and services. Also answers variant and stock questions — put the requested option in attributes so the result carries that variant's inventory.

Parameter	Type	Required	Description
primarySearchCriteria	string[]	No	Search modes. Values: collection, sku, barcode, productName, productType, attributes, price, general, related, complementary. A bare string is accepted and wrapped in an array.
productHandles	string[]	No	Handles from /products/handle-name URLs. Default [].
productLimit	number	No	How many products to return. Default 10.
sortBy	string	No	One of relevance, best_selling, newest, price_low, price_high, similar, complementary.
availability	string	No	One of all, in_stock, out_of_stock, available, unavailable.
minPrice	number	No	Lower price bound.
maxPrice	number	No	Upper price bound.
priceCurrency	string	No	ISO 4217 code, only when the customer names a currency.
isNextPage	boolean	No	True when paging through more of the same results.
sku	string	No	SKU, part number, model number, or catalog code. Pair with sku in primarySearchCriteria.
barcode	string	No	Barcode, UPC, EAN, or ISBN.
productCollection	string	No	Collection, category, or product line named by the customer. Pair with collection in primarySearchCriteria.
attributes	string	No	Attributes as key:value, key:value. Common keys: color, material, size, brand, style, pattern, gender, productType, productName, features. An object or an array of {attribute, value} is also accepted and normalized.

Returns { "products": [ ... ] }. Each product carries productUrl, inventory, and a variants array with per-variant id, options, price, SKU, and barcode. Returns the text No products found. when nothing matches.

product_faq_lookup

Returns FAQs and detail for one product. Call product_lookup first and copy the id verbatim.

Parameter	Type	Required	Description
productId	string	Yes	The productId from a prior product_lookup result.
productTitle	string	No	The product title, used to widen the match.
productUrl	string	No	Accepted by the schema but ignored by the MCP handler. Sending it changes nothing.

Returns { "productFaqs": [ ... ] }, or the text No product FAQs found.

manage_cart

Reads and edits the Shopify cart. MCP is stateless, so the cart id is explicit on every call.

Parameter	Type	Required	Description
action	string	Yes	One of get, add, update, remove.
cartId	string	Conditional	Required for get, update, and remove. Optional for add — omit it to create a new cart.
lineItems	object[]	Conditional	Required for add, update, and remove. Omit for get. Fields below.

Each entry in lineItems:

Field	Type	Required	Description
lineItemId	string	No	Cart line id from a prior get, in the form gid://shopify/CartLine/{uuid}?cart={token}. Copy it verbatim. Preferred for update and remove.
variantId	string	No	gid://shopify/ProductVariant/{id}. Preferred for add.
productId	string	No	gid://shopify/Product/{id}. Used when no variant id is available. A single-variant product resolves; a multi-variant product prompts for the option.
productHandle	string	No	URL slug from /products/<slug>. Last resort.
variantOptions	string	No	Option string such as Black / 2, used to pick the variant.
quantity	number	No	For add, how many to add, default 1. For update, the new absolute quantity, default 1. For remove, how many to take out — omit to remove the whole line.

Returns { "cartId": "...", ... } with the line items, prices, total, and checkout URL. get on a missing cart returns {"error": "Cart not found or expired"}. add with nothing resolvable returns {"error": "No valid product variants found. Use product_lookup first to get variantId."}. update or remove without cartId returns {"error": "cartId is required for \"update\"."}.

---

Registered by their own switch

collection_lookup

Searches collections and categories. Registered by AI agent > Training data > Collections, which is off by default — this is the one tool most stores never see.

Parameter	Type	Required	Description
query	string	No	Search text, for example summer or new arrivals.
limit	number	No	Maximum collections returned. Default 10.
listAll	boolean	No	Set true to list every collection instead of searching. Default false.
includeProducts	boolean	No	Accepted by the schema but ignored by the MCP handler. Products inside a collection do not come back over MCP — call product_lookup with productCollection instead.

Returns { "collections": [ { "title", "description", "image", "collectionId", "url" } ] }, or the text No collections found.

discount_lookup

Finds discounts and promotions. Registered by AI agent > Training data > Discounts, off by default. All four parameters are optional; sending none returns the store's general offers.

Parameter	Type	Required	Description
productIds	string[]	No	gid://shopify/Product/... values. From cart data, take merchandise.product.id, not merchandise.id, which is the variant.
productTitles	string[]	No	Product titles. From cart data, take merchandise.product.title.
collectionTitles	string[]	No	Collection titles the customer named.
codes	string[]	No	Specific discount codes. Pass one to get that code's own conditions instead of the best general offer.

Returns { "discounts": [ ... ] } with codes, requirements, and benefits, or the text No discounts found.

size_guide_lookup

Returns the size chart matched to one product. Registered by AI agent > Instructions > Assistant skills > Size guide, off by default, Pro plan.

Parameter	Type	Required	Description
productId	string	Yes	The productId from a prior product_lookup result.
intent	string	No	One of fit_recommendation, show_chart, dimensions. Accepted by the schema but ignored by the MCP handler — the same chart comes back either way.
customerMeasurements	object	No	Measurements as key-value pairs, using the keys from measurementFields in a prior call. Values may be strings or numbers.

Returns { "sizeChart": "<markdown table>" }, plus measurementFields when the guide defines them and customerMeasurements echoed back when you sent any. Errors: No productId provided. Use product_lookup first., Size guide not found for this product.

Do not use this for stock questions. product_lookup answers whether size XL is available.

check_order_status

Tracks an order. Registered by AI agent > Instructions > Assistant skills > Order tracking, on by default, Basic plan or higher.

Parameter	Type	Required	Description
searchMethod	string	No	track_by_order_number or track_by_tracking_number. Defaults to track_by_order_number, or to tracking number when only a tracking number is supplied.
orderInfo	object	No	Customer-supplied details. Defaults to {}. Fields below.

Fields inside orderInfo:

Field	Type	Required	Description
orderNumber	string	Conditional	Required for track_by_order_number. Strip any leading #.
email	string	Conditional	Verifies the order. Either email or phone is required for track_by_order_number.
phone	string	Conditional	Alternative to email.
trackingNumber	string	Conditional	Required for track_by_tracking_number.

Returns { "order": { ... } } with status, tracking, items, and address, plus deliveryFaqs when your knowledge base has matching shipping content. Missing fields return {"error": "Order number is required for order lookup. Email or phone number is required for order verification"} before any lookup runs.

customer_support

Runs an after-sale request. Registered by AI agent > Instructions > Assistant skills > After-sale support, on by default.

Parameter	Type	Required	Description
issueType	string	Yes	One of returnRefund, cancelOrder, issueOrder, editOrder.
customerData	object	No	Details gathered so far, used to pre-fill the form. Defaults to {}. Fields: orderNumber (string), issueDetails (string), email (string).
isConfirmed	boolean	No	Set true only after the customer explicitly agrees to proceed.
isDeclined	boolean	No	Set true only after the customer explicitly declines.
isSubstantiveQuery	boolean	No	Default true. Set false only for a greeting or thanks with no after-sale intent.

Returns the configured response for that request type: the confirmation prompt on the first call, then the outcome once isConfirmed is true. The transfer method and form fields come from your after-sale settings, per issue type.

human_agent_transfer

Hands the conversation to a person. Registered by AI agent > Instructions > Assistant skills > Human handover, on by default. Two steps: ask, then fire.

Parameter	Type	Required	Description
triggerType	string	Yes	One of customer_request, ai_cannot_answer, repeated_question, negative_sentiment, intent_rule. Judge it at the turn the need first arose, not at the confirmation turn.
customerRequest	string	No	The customer's own words asking for a person.
matchedIntentRule	string	No	The rule name, when triggerType is intent_rule.
isConfirmed	boolean	No	Default false. First call must be false, which asks the customer to confirm. Send true on the follow-up, with the same triggerType.
isDeclined	boolean	No	Default false. True only when the customer says no after being asked.
isSubstantiveQuery	boolean	No	Default true. Set false only for a non-substantive message with no request to reach a person.

Returns the handover response, which reflects your business hours and current agent availability — the answer differs outside working hours.

---

Need help?

Contact the Chatty support team from your dashboard. Include the tool name, the timestamp of a failing call, and the returned error message.

For connection, authentication, and security, see the MCP overview.