# Tool reference

All 17 Shop MCP tools, what each one needs, how they're annotated, and the arguments they have in common.

Shop MCP serves 17 tools. `tools/list` returns each one with a description, an input schema and annotations. The guides linked below show how to use them, and the input schema is the exact reference for each argument.

| Tool | What it does | Sign-in | CLI |
| --- | --- | --- | --- |
| `search_catalog` | Searches for products by text, a similar product or a photo | Optional | `shop search` |
| `lookup_catalog` | Finds products from IDs, GTINs or URLs you already have | Optional | `shop catalog lookup` |
| `get_product` | Gets one product's details and options, and resolves a variant | Optional | `shop catalog get` |
| `create_cart` | Saves items in a cart at one merchant | Optional | `shop cart create` |
| `get_cart` | Reads a cart | Optional | `shop cart get` |
| `update_cart` | Replaces a cart's contents | Optional | `shop cart update` |
| `create_checkout` | Starts a checkout at one merchant | Optional | `shop checkout create` |
| `get_checkout` | Reads a checkout | Optional | `shop checkout get` |
| `update_checkout` | Replaces a checkout's details, such as items or delivery | Optional | `shop checkout update` |
| `complete_checkout` | Pays for a checkout and places the order | Optional | `shop checkout complete` |
| `search_orders` | Searches the shopper's orders and shipments | Required | `shop order search` |
| `get_account` | Reads the shopper's profile, addresses and payment options | Required | `shop account` |
| `create_approval` | Asks the shopper to approve a purchase outside Shopify | Required | `shop approval create` |
| `get_approval` | Reads an approval, and returns the card once it's approved | Required | `shop approval get` |
| `update_approval` | Changes an approval's limit, items, totals or address | Required | `shop approval update` |
| `cancel_approval` | Cancels an approval | Required | `shop approval cancel` |
| `complete_approval` | Records how the purchase went | Required | `shop approval complete` |

With a token, the tools that don't require sign-in run as the signed-in shopper. [Authentication](authentication.md) covers tokens, and these guides cover the tools:

- [Search the catalog](search.md): `search_catalog`, `lookup_catalog` and `get_product`.
- [Check out](checkout.md): the cart and checkout tools.
- [Track orders](orders.md): `search_orders`.
- [Connect a Shop account](sign-in.md#check-the-connection): `get_account`.
- [Approvals](approvals.md): the five approval tools.

There are no tools to cancel a cart or a checkout, or to read a single order by its ID.

## Annotations

| Tools | `readOnlyHint` | `destructiveHint` | `idempotentHint` |
| --- | --- | --- | --- |
| `search_catalog`, `lookup_catalog`, `get_product`, `get_cart`, `get_checkout`, `search_orders`, `get_account` | `true` | `false` | `true` |
| Every other tool | `false` | `true` | `false` |

`get_approval` counts as a write: reading an approved approval has Shop issue a card. Every tool has `openWorldHint: true`, because each call reaches the catalog, a merchant or Shop.

## Arguments

| Tool | Arguments | Required |
| --- | --- | --- |
| `search_catalog` | `catalog`: `query`, `like`, `context`, `filters`, `pagination`, `catalog_id`, `signals` | `catalog`, with `query` or `like` |
| `lookup_catalog` | `catalog`: `ids`, `context`, `filters`, `signals` | `catalog.ids`, 1 to 50 |
| `get_product` | `catalog`: `id`, `selected`, `preferences`, `context`, `filters`, `signals` | `catalog.id` |
| `create_cart` | `shop`, `cart`, `meta` | `shop`, `cart.line_items` |
| `get_cart`, `get_checkout` | `shop`, `id` | Both |
| `update_cart` | `shop`, `id`, `cart`, `meta` | `shop`, `id`, `cart.line_items` |
| `create_checkout` | `shop`, `checkout`, `meta` | `shop`, `checkout.line_items` |
| `update_checkout` | `shop`, `id`, `checkout`, `meta` | `shop`, `id`, `checkout.line_items` |
| `complete_checkout` | `shop`, `id`, `checkout`: `payment`, `signals`, and `meta` | `shop`, `id`, `checkout.payment` |
| `search_orders` | `query`, `activity`, `date_from`, `date_to`, `pagination` | None |
| `get_account` | None | None |
| `create_approval` | `approval`, `meta` | `approval` |
| `get_approval`, `cancel_approval` | `id`, and `meta` for `cancel_approval` | `id` |
| `update_approval` | `id`, `approval`, `meta` | `id`, `approval` |
| `complete_approval` | `id`, `result` | Both |

### `shop`

The merchant for a cart or checkout. Pass the `seller.domain` of the product's offer exactly, as a hostname with no scheme or path, such as `tog24.myshopify.com`. Each cart or checkout belongs to one merchant, and every later call on it takes the same `shop`.

### `id`

The ID that a create returned. Cart and checkout IDs are opaque, so pass them back exactly as you got them. Approval IDs are UUIDs.

### `meta.idempotency-key`

A UUID that marks repeated sends of one write as the same operation. Reuse it when you repeat a request, and make a new one for each new operation. `complete_checkout` makes one from the request when you leave it out, but never send a completion twice. [Retries](errors.md#retries) explains when it's safe to repeat a write.

`meta` takes nothing else. Shop MCP adds its own agent profile when it calls the catalog and merchants.

### `signals`

The catalog, cart and checkout tools accept `signals`, with facts your platform observed about the shopper's request:

| Signal | Value |
| --- | --- |
| `dev.ucp.buyer_ip` | The shopper's IP address |
| `dev.ucp.user_agent` | The user agent of the shopper's browser or app |

Shop MCP passes them on to the catalog or merchant. Send them only when your platform observed them, as a server acting for a shopper's browser can. Without them, Shop MCP uses what it sees of the request itself: its IP address, or the leftmost `X-Forwarded-For` address, and its `User-Agent` or the MCP client name.

When you update a cart or checkout, remove the `signals` that came back in the copy you read before you send it.

## Results

A result has the tool's document in `structuredContent`, and the same document as a JSON string in `content[0].text`, for clients that only read text. The tools don't publish an output schema.

Documents can carry `messages`, with warnings and errors to show the shopper or act on, and `next`, with Shop MCP's suggestions for an agent working with the result. A failed call has `isError: true`, and some failures have only text. [Errors and retries](errors.md) covers each kind.