Chat tools
The built-in tools an agent version can call (product cards, clarifying questions, your own site's pages, web search, and web page reading) and how to choose them per version.
Beyond the connectors it can call, a version has its own list of chat tools: built-in features the assistant itself decides to call to answer richer than plain text. The four below render as a component inline in the chat, not as a wall of text. Two more, covered further down, let it answer from the pages of your own site, and two give it access to the open web.
Not the same as capabilities
Chat tools are things the assistant chooses to call. A version also has capabilities (file upload, voice dictation and suggested replies), which the assistant never calls itself. The two are configured in separate checklists on the same form.
| Tool | What shoppers see |
|---|---|
| Product carousel | A swipeable row of product cards for the products the assistant settled on, each with a price, a short pitch on why it fits, and (when the assistant flags it) a short badge over the photo (e.g. "On sale"). Tapping the photo or title opens the product page; an "Add to cart" button sits below it, unless your connector can't add that product to the cart. A product that can't go to the cart gets a "View product" button in its place, which opens the product page in a new tab. A product with 2 or more variants also gets a picker that swaps the photo and price instantly. For screen readers, the carousel is named by its number of products ("4 products") and each card by its position ("2 of 4"), in the chat panel's language. |
| Product comparison | A side-by-side table of 2 to 4 products, with the assistant's pick highlighted, a 1-to-5 star rating plus a short take for every product, and (on any product with 2 or more variants) a picker that swaps that column's own photo and price instantly. |
| Product detail | A full product page inline in chat: a photo gallery, the price, a short pitch (a one-line hook and up to 3 benefits), and the "Add to cart" and "View product" buttons. A product with 2 or more variants also gets a picker: choosing a variant puts its own photo, when it has one, first in the gallery and updates the price instantly. See Product detail below for the layout and the gallery. |
| Clarifying questions | Up to 4 quick multiple-choice questions (with a free-text option) the assistant can ask before it searches or recommends, instead of asking in plain text. |
Site page tools
Two tools let the assistant answer from the pages of your own site that AISA has read, for what your catalog does not hold: how a product is used, what is in it, how to size it, your delivery and returns terms, your brand.
| Tool | What it does |
|---|---|
| Site page content | Reads what AISA stored for one page: its facts, its sections under their titles and, when asked for, its shopper reviews. |
| Site page search | Searches your read pages for a topic and returns up to eight, each with a short passage, or up to twenty when the question names a product reference that many pages list. Finds products too, but only when the site has no catalog connector. |
Like the web tools, they render no card. While one runs the chat shows "Checking the page…" or "Searching the site…", and the answer comes back as an ordinary reply. They only read what AISA already stored. They never fetch a page, and a conversation with no site never has them.
Site page content
The assistant names the page in one of four ways:
- A product from your catalog, found by a catalog tool earlier in the conversation. On Shopify it is found by its Shopify product number, so a renamed address still works, otherwise by the address of its page.
- A page a search returned earlier in the conversation.
- A path or an address on your site, for example one the shopper pasted. It is looked up among the pages AISA read, never fetched. An address on another site finds nothing.
- The page the shopper is on now. This works when the page signal is on and AISA holds a read copy of that page: the assistant is then told that the content is available.
It gets the page's facts and main sections, up to 6,000 characters, or 10,000 when the page lists compatible products, so the list is not cut by the page's own text. Facts that are not questions and answers come first. When the page has text of its own, they take at most 3,000 of the 6,000, so the text still reaches the assistant. The sections follow, then the FAQ in whatever room is left. When the assistant names sections from the list the first answer gives, it gets those in full, up to 12,000 characters. It can name FAQ to read the page's questions and answers, which the list shows when the page has some. A request that names FAQ gets up to 20,000 characters instead of 12,000, so a long list still reaches the entry the assistant needs. It reads shopper reviews only when it asks for them. A page that is not read, or that AISA does not hold, gives no content, and the assistant is told to say it has no information. At most 4 calls per turn.
Site page search
The search is full text on your read pages, with accents ignored. It looks in the conversation's language first, and in your other languages only when that finds nothing. The assistant can narrow it by page type. At most 3 calls per turn.
Pages come back in four groups, best match first within each: pages that hold every word of the question, then pages that hold every product reference it names, then pages that hold at least one of those references, then pages that hold some of its words. A product reference is a word of five characters or more with at least two letters and two digits, like CE701100. A quantity or a size is not one: digits, possibly multiplied, followed only by letters, like 500ml, 2x500ml or 140x190cm. So in "ceramic bowl spare part KX204100", the page that lists KX204100 ranks above the pages that only say "spare part", even when thousands of them do.
The search returns up to eight pages. When the question names a product reference, it returns up to twenty, and every page past the eighth holds each reference the question names (or every word of the question). An appliance code can be listed on every spare part that fits it, so the assistant gets more of those pages than the usual eight. The pages past the eighth reach the assistant without a passage: it picks among them by title and address, and can read one in full with Site page content.
How the assistant is told to use them
When a version has either tool, its instructions gain a standing paragraph. The assistant is told to:
- Look in the catalog first for a product, and use the page only for what the catalog record does not say.
- Take price, promotions, availability and stock from the catalog tools only, never from a page.
- Say where a fact comes from, and treat the content as dated: it carries the date of the read and may be out of date.
- State a safety fact (pregnancy, age, allergens, contra-indications, dosage) only when the catalog or a page says it, naming the page, never from general knowledge or from a shopper review.
- Treat shopper reviews as opinions, not as properties of the product.
- Quote a contractual fact (a return period, a fee, a guarantee length, a free-shipping threshold) as the page writes it.
- Say it has no information when nothing matches, instead of answering from general knowledge.
These are instructions to the model, not a guarantee. One rule does not depend on the model: when the site has a catalog connector, a page search never offers a page as a product.
A site with no catalog connector
When the version has no connector that searches products (Shopify or Adobe Commerce, for example), your product pages are the only product source. Site page search then returns the product a page declares to sell, with the price as shown on that page. The assistant can show it as a product card. The card links to the page and has no Add to cart button, since there is no catalog to add from. On a product carousel or a comparison it has a View product button instead, which opens the page in a new tab. The assistant is told to state that price only as read on the date of the read, and that it may have changed, and never to state a promotion or a stock level. A page that declares its product out of stock gives no card, unless the version has the Out-of-stock products capability on: the card then shows the product as out of stock, with View product and no Add to cart.
Turn them on
Both tools are on by default for a new Shopping assistant version. A version created before they existed does not have them: edit the version, tick them under Chat tools and save (as a new version when it's locked). The assistant can read only pages that are Read in Pages, so a site that has read none gets nothing from them.
Web search and page reading
Two more tools give the assistant access to the open web, for questions the catalog, connectors, and the model's own knowledge can't answer: comparing against a product outside your catalog, checking a factual claim, or pulling up independent reviews.
| Tool | What it does |
|---|---|
| Web search | Searches the live web and gets back a short list of results (title, URL, a content snippet) for the assistant to read and answer from. |
| Web page reading | Fetches and reads the full content of one specific page, typically a URL a prior web search turned up, or one a shopper pasted in. |
Unlike the five tools above, these don't render a card. While the assistant is using one, the chat shows a short status ("Searching the web for you…" / "Reading that page…"); the answer itself comes back as an ordinary written reply, not a component.
Both tools are capped at 3 combined calls per conversation turn. Once that's used up, the assistant answers with what it already has instead of continuing to search or fetch.
The Tools page
Every site has a Tools page listing all nine chat tools above: Tools in the dashboard sidebar, under Assistant, or /dashboard/sites/{siteId}/tools.
Each row shows the tool's name, its one-line description, and a Used by column: Active on N agents when N of the site's agents have that tool enabled on the version each one keeps as its live one, Not used otherwise. That version counts even for an agent that doesn't answer on the site today: the one it answered with before it was taken offline, or a new agent's V1. A tool you're trialling on any other version still reads Not used.
This page never turns a tool on or off. Enablement belongs to an agent's configuration version (see Choose a version's tools below); the Tools page only says what exists, whether it's live, and (for the two web tools) how it behaves.
Seven of the nine tools have nothing to configure at site level; their row shows a dash instead of an actions menu. Web search and Web page reading each open their own configuration page: click the row, or use Configure in its ··· menu (which also has View documentation, opening this page in a new tab).
Configuring tools requires a permission
Opening the Tools pages requires the Agents: View permission; saving a configuration requires Agents: Edit. Without either, Tools doesn't appear in the sidebar and going there directly shows a restricted-access message. A view-only member sees a configuration page read-only: the settings are all visible, but the controls are disabled and no card has a Save button. See Roles to check or grant these on a custom role.
Restrict which domains they can reach
Both tools reach the whole open web by default: no configuration needed to make them useful. To narrow one (only your own domain plus two retailers) or block one (a named competitor, say), open its configuration page from the Tools page.
Each page presents that tool's domain policy as one of three modes:
- Open web: no restriction (the default).
- Allow only certain domains: only the domains you list, and their subdomains, are reachable; everything else is blocked. While the list is empty this behaves exactly like open web; the list's description says so.
- Block certain domains: the domains you list, and their subdomains, are blocked; every other domain stays reachable.
Add domains one at a time as bare host names: example.com, no https://, no path, no port. Anything else is rejected with a message naming what you typed. Entries are lower-cased for you, a domain already in the list is ignored rather than duplicated, and a list holds up to 100 domains. Switching mode clears the list you were editing: an allow-list carried over under a "blocked" label would mean the exact opposite, so a mode change starts from empty.
Nothing is written until you press Save at the bottom of the card you edited, and it stays disabled until you actually change something there. A successful save confirms with a short toast. Leaving the page first discards your edits; there's no "unsaved changes" warning. Widening a policy back to Open web isn't confirmed separately either; Save is the deliberate act.
A saved policy belongs to the site, not to an agent version. It applies to every agent version on the site as soon as you save: no new version to save, nothing to put live.
The two policies are fully independent: set both
Web search and page reading each have their own domain policy, edited only on their own page. Neither page shows or touches the other's. Restrict search but leave page reading open and the assistant searches inside your allow-list, then happily reads any page it's handed. Whatever you want to apply to both, save it twice.
Web search
Configured at Tools → Web search (/dashboard/sites/{siteId}/tools/web-search). Its policy decides which sites a search may return results from. The restriction is sent to the search provider and re-applied to the results that come back, so a domain you blocked can't reach the assistant even if it slips through the provider's own filtering.
Domains, modes, and saving work exactly as described above; there's nothing web-search-specific beyond the policy itself.
Web page reading
Configured at Tools → Web page reading (/dashboard/sites/{siteId}/tools/web-fetch). Its policy is separate from web search's and decides which pages the assistant may fetch, including a URL a shopper pasted into the chat. A blocked host is refused before any external request is made.
This page holds one setting web search doesn't have: Always enable JavaScript rendering. Some pages only show their real content after running JavaScript. Web page reading already retries once with rendering on when a plain fetch comes back close to empty. Turning this on skips that wasted first attempt for a site you already know needs it. Off by default, and every retrieval is a little slower once it's on. It sits in its own card with its own Save, so switching it doesn't commit whatever you may have been editing in the domain list above, and saving the domain list doesn't reset it.
Defaults depend on the agent's type
- A Shopping assistant agent starts with the five card tools and the two site page tools above enabled on a new version: the checklist is there to turn some off, not to opt in. Web search and Web page reading are the exception: they start off for every agent type, Shopping assistant included, each an explicit opt-in.
- A Custom agent (an agent whose type is Custom, which starts with no built-in persona at all: everything it does comes from that version's own instructions) starts with nothing in the checklist enabled. You decide which, if any, it can use.
Choose a version's tools
Chat tools are part of an agent's configuration version, in the same form as its connectors.
Open the agent and go to its Capabilities tab. You're already editing its current configuration, no separate "new version" step needed (see Edit a version).
Under Chat tools, tick the ones this version should be able to use; each row shows the tool's name and a one-line description. The list is prefilled from the version you're editing. The Web search and Web page reading rows carry a small cog on the right that opens that tool's configuration page; it's a shortcut only, and clicking it never ticks or unticks the tool.
Save, as usual: on the version you're on, or as a new version. Your tools apply once that version goes live.
A tool you leave unticked isn't just hidden from the assistant's replies: it's never made available to the model in the first place, so it has no way to call it.
Fixed for that version
Which tools a version can use is part of that version and can't be changed afterward. Like its instructions and connectors, changing the set means creating a new version.
Product detail
The product detail card spotlights one product. Its layout follows the width the card gets, not the size of the shopper's screen, and the same rule applies wherever the conversation appears: the chat panel on your storefront, the AI Storefront, the playground, or a conversation's transcript in the dashboard.
- On a wide card (the storefront chat panel on a computer, the playground), the photos sit in a column on the left and the details on the right, so the name, price and buttons show next to the photo.
- On a narrow card (a phone), the photos span the top of the card and the details follow underneath.
The details read in this order: the product name (cut after two lines), the price (with the original price struck through when there is one), the assistant's pitch, the variant picker when the product has 2 or more variants, then the "Add to cart" and "View product" buttons. The two buttons share one row, at equal width when both labels fit in half of it. When the labels can't fit side by side (a longer translation on a narrow card), each button takes a full row of its own, so a label is never cut off. "View product" opens the product on your site in a new tab. When your connector can't add the product to the cart (an Adobe Commerce bundle, for example), there is no "Add to cart" and "View product" takes the whole row.
The pitch is written by the assistant for what the shopper asked; your own product description is never shown on the card. It's a one-line hook followed by benefits, each a short label and a few words of detail. The assistant is asked for exactly 3 benefits. The card shows at most 3, and still shows a pitch with 2.
The gallery opens on the selected variant's own photo. When that variant has none, it opens on the product's first photo that isn't another variant's own photo, or on the product's first photo if every photo belongs to another variant. The product's other photos follow in catalog order. Photos that belong to the product's other variants are left out, so a shopper looking at one shade doesn't swipe into the others. Choosing a different variant rebuilds the gallery the same way for that variant and returns to its first photo.
The first photo is shown whole on a white background, never cropped; the photos after it fill their frame. With more than one photo, dots over the bottom of the photo show the position. Shoppers swipe between photos; with a mouse, previous and next arrows also appear while the pointer is over the gallery or it has keyboard focus.
For screen readers, the gallery is named "Photos of" followed by the product name, and each photo by its position ("2 of 3"). A single photo is read as a plain image, by its alt text. These names, the arrows' labels and the words "carousel" and "slide" are in the chat panel's language, or in your dashboard language in a conversation's transcript.
Quick replies
Quick replies are no longer a chat tool. The assistant doesn't call them and this checklist doesn't list them: they are the Suggested replies capability, which the server generates after each answer. See that page for when a row shows up and when it stays silent.
Clarifying questions and the composer
When the assistant asks a clarifying question, answering it (or skipping or closing it) is what lets the conversation continue. Typing and sending a new message instead does not answer the pending question for you; the composer doesn't currently hold your next message back until the open question is resolved.
Add to cart
"Add to cart" on a product carousel, comparison, or detail card doesn't call a cart API directly: it sends a message asking the assistant to add that product to the cart, and the assistant takes it from there in the conversation.
The shopper's message reads "Please add product name to my cart.", with the variant in parentheses for a product that has several. The conversation view in the dashboard shows the same sentence. The API and the MCP get_conversation tool return it as text, followed by an add_to_cart_request block that carries the product id (and the variant id and label). That block records the request, not a confirmed cart write.
The button also works while the assistant is still writing a reply. It switches to Added at once, but its message waits until the reply finishes, never going out at the same time as another one. Tap several products during one reply and their messages go out one at a time, in the order tapped, each after the assistant has answered the previous one. Stopping the reply doesn't cancel a waiting message. Starting a new conversation before it goes out does drop it.
If that reply ends on a clarifying question, the waiting message holds back so it doesn't cancel the question. It goes once the shopper answers, skips or closes the question and the assistant has replied, or once they type a message of their own and it has been answered. If they leave the question unanswered and do nothing else in the chat, it's never sent, even though the button already reads Added.
A tap made while a question is already on screen doesn't wait: it's sent at once and sets the question aside, as typing would. Messages still waiting go first, in order, and the new tap follows once the assistant has answered them.
Added confirms the tap, not the cart: what happens to the cart depends on how the assistant answers that message. On a Shopify store with the web tag, once the assistant has changed the shopper's own cart, the panel shows the cart card with the cart as it stands.
Instructions
Write and manage the reusable, typed instruction blocks that agent versions on a site compose into their system prompt.
Capabilities
File upload, voice dictation, suggested replies and out-of-stock products, the extras a version can switch on beyond its chat tools. All off by default, toggled per agent version.