Tool reference
9 tools, generated from the array the server actually answers
tools/list with — so a tool added to the server is a tool on this page on the
same deploy, and one removed cannot linger here.
| Tool | What it does |
|---|---|
| get_shop any key | Get shop |
| list_orders any key | List orders |
| get_order any key | Get order |
| list_products any key | List products |
| get_product any key | Get product |
| list_contacts any key | List contacts |
| get_contact any key | Get contact |
| create_contact needs a write key | Create or update a contact |
| tag_contact needs a write key | Tag a contact |
Argument spelling
Arguments use the snake_case spelling, which differs from the REST request
body in a couple of places: payment_status, send_opt_in. That is the
naming convention — a query parameter and a JSON body
spell things differently, and a tool argument follows the query-string side.
Field names in the result are the REST spelling, camelCase, because the
result is the REST object.
Paging
The list tools take limit and cursor, exactly as
the REST API does, and their results carry has_more and
next_cursor beside the data.
limit defaults to 25 and is capped at 100; asking for
more is clamped rather than refused.
What a result looks like
Every tool answers with both structuredContent and a text block carrying the
same JSON serialised. That looks redundant and is what the specification
recommends, for the reason it looks redundant: a client that does not read
structured content still shows the model something useful rather than an empty
result.
A refusal comes back as isError: true with a sentence — not as a JSON-RPC
error. See protocol for why those are different things
to a model.
The tools
Descriptions below are exactly what the server sends to a model. Not paraphrased for a human reader, on purpose: when an assistant does something surprising, this text is the reason — and a prettier version here would send somebody looking for a cause that is not in the code.
get_shop
The shop this key belongs to: its handle, display name, currency and time zone. Call this first when you need to know which currency amounts are in, or which time zone dates should be read in.
Arguments
Takes none.
list_orders
Orders, newest first. Use email to find everything one customer has bought, status for where an order is in fulfilment (new, confirmed, shipped, completed, cancelled, refunded), and payment_status for whether the money arrived (unpaid, paid, refunded). An order can be paid but not yet shipped, so the two are separate questions and answering one does not answer the other.
Arguments
| Argument | What it does |
|---|---|
| status string · optional | Fulfilment stage, e.g. shipped. |
| payment_status string · optional | Money state, e.g. paid. |
| email string · optional | Exact customer email, case-insensitive. |
| limit integer · optional | How many to return. Defaults to 25, at most 100. |
| cursor string · optional | Pass next_cursor from a previous call to get the following page. Omit for the first page. |
get_order
One order in full, including every line item, the delivery address and any tracking details. Use it after list_orders when you need the items rather than the summary.
Arguments
| Argument | What it does |
|---|---|
| id string · required | The order id. |
list_products
The shop's catalogue, newest first. published filters to what buyers can currently see; omit it to include drafts. stock is null on products that do not track inventory — that means 'not counted', which is not the same as sold out.
Arguments
| Argument | What it does |
|---|---|
| kind string · optional | One of physical, digital, service, event. |
| published boolean · optional | Only published, or only drafts. |
| limit integer · optional | How many to return. Defaults to 25, at most 100. |
| cursor string · optional | Pass next_cursor from a previous call to get the following page. Omit for the first page. |
get_product
One product in full, including its variants and their individual stock.
Arguments
| Argument | What it does |
|---|---|
| id string · required | The product id. |
list_contacts
People on the shop's list. Set consented to true for only those who opted in to marketing email — everyone else is a customer who never agreed to be emailed, and must not be added to a mailing list or newsletter tool. marketingConsentAt on each record is when they agreed, or null if they never did.
Arguments
| Argument | What it does |
|---|---|
| tag string · optional | Only contacts carrying this tag. |
| email string · optional | Exact email, case-insensitive. |
| consented boolean · optional | True for only those who opted in to marketing email. |
| limit integer · optional | How many to return. Defaults to 25, at most 100. |
| cursor string · optional | Pass next_cursor from a previous call to get the following page. Omit for the first page. |
get_contact
One person on the shop's list, with their tags and consent state.
Arguments
| Argument | What it does |
|---|---|
| id string · required | The contact id. |
create_contact write
Adds somebody to the shop's list, or updates and merges tags onto them if they are already on it. This CANNOT grant marketing consent — a new contact is always created without it, whatever you pass. To get consent, set send_opt_in to true: that emails the person a confirmation link, and consent is recorded only when they click it. Never tell the seller a contact is subscribed on the strength of this call alone.
Arguments
| Argument | What it does |
|---|---|
| name string · optional | No description in the schema. |
| email string · optional | No description in the schema. |
| phone string · optional | No description in the schema. |
| tags string[] · optional | Merged with any tags they already have; never replaces them. |
| send_opt_in boolean · optional | Email this person a double opt-in confirmation link. Requires an email address. |
tag_contact write
Adds and removes tags on one contact. Tags are how a seller segments their list, so this is what changes who a future broadcast reaches. Omitted tags are left alone — there is no way to replace the whole set, on purpose.
Arguments
| Argument | What it does |
|---|---|
| id string · required | The contact id. |
| add string[] · optional | No description in the schema. |
| remove string[] · optional | No description in the schema. |