Tools reference
The complete surface. Every tool is read-only and free to call. What each one is for is in the tool guide.
All tools
| Tool | Parameters | Answers |
|---|---|---|
get_setup_status | — | Is the widget live on the storefront, and if not, why? |
get_offers | query? type? status? limit? | Which offers exist, and which are live? |
get_offer_details | id | How is this one offer configured? |
get_analytics | start? end? offer_id? | Revenue, orders, attach rate, top offers |
get_plan_status | — | Which plan, how much used, capped or not |
Parameters marked ? are optional. Only get_offer_details has a required one.
Accepted values
| Parameter | Accepts |
|---|---|
type | fbt, volume-discount, mix-match-bundle, bundle-builder, product-fixed-bundle, upsell |
status | active, scheduled, expired, draft, all |
start, end | YYYY-MM-DD |
limit | A whole number. Defaults to 10 |
upsell is the offer type the app calls Product Recommendation. The other five match their
names.
Defaults worth knowing
| Tool | If you pass nothing |
|---|---|
get_offers | The 10 most recent offers, any type, any status |
get_analytics | The last 30 days |
The get_offers default of 10 is the one that quietly misleads. Nothing in the answer says the list
was cut short, so "I have 10 offers" and "I have 10 of 47 offers" read identically. Ask for a
limit whenever the total matters.
The same data over REST
The same token also works against the Store API, which serves this
data as plain GET requests for scripts rather than assistants. The base URL for your store is on
the Connect to AI and the API card in Settings → Integrations.
| Tool | Roughly matching endpoint |
|---|---|
get_setup_status | GET /diagnostic |
get_offers | GET /offers |
get_offer_details | GET /offer/:id |
get_analytics | GET /analytics |
get_plan_status | GET /subscription |
The REST responses are not field-for-field identical to the tool results — the tools trim and reshape what they return. Read a tool result as the reference for what an assistant sees, not as the API contract.
Limits
| Requests | 60 per minute, per connection |
| Analytics currency | USD, regardless of the store's own currency |
Rate limits are counted per connection, so one tool cannot exhaust another's budget. Over the limit,
the server answers 429 with a Retry-After header.
What is deliberately absent
- No write tools. Not restricted — not implemented. Nothing an assistant calls can create, change, or delete an offer, a discount, or a setting.
- No customer data. No names, emails, addresses, or individual orders.
- No product catalogue. Only the products already placed inside an offer.
- No theme or storefront source.
get_setup_statusreads your theme server-side and returns conclusions; the files themselves never leave. - No internal identifiers. The store's record id and Shopify access token never leave the server.
- No pricing.
get_plan_statusreports your store's plan and usage, never a price list.