---
title: "Calling tools"
description: "How the merchant MCP server lists its tools, takes their arguments and answers them."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Calling tools

The server at `https://mcp.sherpo.io` offers 284 tools in all. A connection sees only the ones it may call, and every tool has its own page under [Tools](/merchant-mcp/tools) with its arguments, its answer and its errors.

## What the server says first

When a client connects, the server sends these instructions, followed by a summary of the [rich text](#rich-text) format:

> Sherpo's merchant tools act on the stores this connection reaches, which `list_merchants` lists with their businesses. A store tool takes `store` when the connection reaches more than one, and acts on that store's business. Most writes carry no idempotency key: after a failed write, read the state back before trying again. `record_order` takes `source_key` and `record_portfolio_event` takes `idempotency_key`. Send an order's same `source_key` on every resend: a `conflict` at `source_key` then means the first call landed, and `current` names its order, even when the resend's customer, currency or lines changed since; when they did, read that order back with `get_order` to check it is the same sale. Send an event's same `idempotency_key` with the same arguments: the event recorded comes back. The key is its portfolio's own, and on that portfolio other arguments are a `conflict` at `event`, and `current` names the event recorded. A private file comes back inside `get_asset_url`'s result, never through its `url`.

The server offers tools only: no prompts and no resources.

## Listing tools

`tools/list` answers the tools this connection may call, read from its [scopes](/merchant-mcp/scopes), not every tool the server has. A connection holding only the Catalog set lists only the tools its scopes allow. The list follows the connection's current access.

Tools come 50 to a page, with a `nextCursor` while more follow. MCP clients page through it on their own.

Each tool carries:

- `name`: snake case, such as `list_products`.
- `title`: a short title, such as "List products".
- `description`: what it does, the scope it needs and, for a list, its paging, filters, sorts and search.
- `inputSchema` and `outputSchema`: JSON Schema of its arguments and its answer.
- `annotations`: `readOnlyHint` is true for reads. `idempotentHint` is true for reads only: even the two writes that take a key of their own repeat without it (see [Writes and retries](/merchant-mcp/calling-tools#writes-and-retries)). A write has `destructiveHint` false when it only adds, such as [`create_product`](/merchant-mcp/tools/create_product), and true when it may change or remove what is there. `openWorldHint` is always false. [`get_asset_url`](/merchant-mcp/tools/get_asset_url) is marked a write, with `destructiveHint` false, since it hands out a link and records a download as a delivery; nothing else changes.

## Picking a store

A connection reaches one or more stores, of one business or, for a connection the seller picked several businesses for, of each of them. The store picks the business a call acts on. Every tool that acts on a store takes a `store` argument, the id of the store to act on, listed in its schema as one of the connection's stores.

- With one store, `store` may be left out: the call acts on that store.
- With more than one, `store` is required.

A missing or wrong `store` is a tool error, and the connection stays as it is:

- Left out while the connection reaches more than one store: `invalid` with `context: { "path": ["store"], "reason": "required" }`.
- A store the connection was never approved for: `invalid` with `context: { "path": ["store"], "reason": "not a store of this connection" }`.
- A store of a business the connection no longer reaches, such as one the seller removed it from: `not_permitted` with `context.reason` set to `principal`.

Two account tools act on the business instead of a store and take no `store` to act on: [`list_merchants`](/merchant-mcp/tools/list_merchants) and [`get_merchant`](/merchant-mcp/tools/get_merchant). Passing one to `get_merchant` is `invalid` with the reason "not taken by this tool". `list_merchants` takes a `store` of its own, as an object `{ "id": "..." }`, which narrows the list to the business holding that store.

## References

An argument naming a record is an object, never a bare string: `{ "id": "..." }`. Some tools also take a product by its slug, as `{ "slug": "..." }`. The exception is the `store` a store tool takes, a plain string id (see [Picking a store](#picking-a-store)).

```json
{ "order": { "id": "5f0c8d2e-41a7-4b9e-9c3d-2a6f1e8b7c40" } }
```

A reference that matches nothing is `not_found`.

## Lists and paging

A list tool takes one `query` object, every field optional:

- `filter`: per field, with the operators each field takes, such as `eq`, `in` (up to 50 values), `gte` and `lte`. A bare value means `eq`.
- `sort`: `{ "name": "...", "direction": "asc" }` or `"desc"`.
- `search`: text to search for, up to 200 characters.
- `limit`: how many items a page holds.
- `cursor`: the `cursor` of the page before, for the next one.
- `count`: true to also answer the `total`.
- `facets`: fields to answer counts by, for the lists that offer them.

```json
{
  "query": {
    "filter": { "status": { "in": ["draft", "scheduled"] }, "category": "course" },
    "sort": { "name": "created", "direction": "desc" },
    "limit": 50,
    "count": true
  }
}
```

The answer holds `items` and `cursor`, plus `total` and `facets` when asked. Pass `cursor` back for the next page; it is null on the last one.

A page holds 20 items unless `limit` says otherwise, on most lists. Each tool's page says its own most, 100 for most lists and up to 1,000 for a few. Each tool's description also lists the fields it filters, sorts and searches.

Search follows two rules:

- An empty page with a cursor means nothing so far: only a null cursor ends a search.
- A searched page past the count budget comes back without its total and facets, which never means zero.

Where a search covers `id`, an id matches only when typed whole.

## Answers

A successful call answers its result in `structuredContent`, and the same JSON as text in `content`, so a client reading only text sees what the output schema describes. An answer that isn't an object, such as the list [`list_integrations`](/merchant-mcp/tools/list_integrations) answers, is wrapped under `result`:

```json
{
  "content": [{ "type": "text", "text": "{\"result\":[]}" }],
  "structuredContent": { "result": [] }
}
```

A write that takes a long text or binds files answers short, so a call doesn't pay again for what it sent. [`set_body`](/merchant-mcp/tools/set_body), [`edit_body`](/merchant-mcp/tools/edit_body) and [`publish_body`](/merchant-mcp/tools/publish_body) answer the `attachment`, the `asset` the body holds now (the `from` of the next write) and the attachments they `created`, with the `preview` link a set or an edit answers and the `blocks` an edit touched. The writes of products, entries, pages and quizzes answer the record without its long texts, `attachments` and `files`, with the attachments its texts `created`. Pass `full: true` to have those answered too, as the matching read answers them.

A refused call is a tool error with `isError: true`. See [Errors](/merchant-mcp/errors).

## Rich text

Rich text fields, such as a product's description or an entry's teaser, take HTML in a closed format:

- Text: `p`, `h1` (Title), `h2` (Heading), `h3` (Subheading), `br`, marks, links, colored spans and text alignment.
- Structure: lists and task lists, tables, code blocks, `blockquote`, `hr`, `details` with `summary`, and `figure` with `figcaption`.
- Images, videos, audio, slideshows, formulas, diagrams, maps, downloads and other blocks are `<block type="..." props="{...}"></block>` elements. There is no raw `img`, `video` or `iframe`. [`get_body_schema`](/merchant-mcp/tools/get_body_schema) answers each block's props and the values they take, and a prop it doesn't list is refused.

Anything else is refused as `invalid`, with `context.path` naming the field and `context.reason` what is wrong. The server's instructions and each writing tool's description carry the exact list.

```html
<h1>Welcome</h1><p style="text-align: center">Start with <strong>the intro</strong>, then <a href="https://example.com/notes" target="_blank">read the notes</a>.</p>
```

A read answers the stored form, wrapped in `<rich-text version="1">`. Send it back as it is to keep a text unchanged.

To write Markdown instead, pass `text_format: "markdown"` with the write. Every rich text field of the call is converted from Markdown (CommonMark with tables, task lists and strikethrough), then checked the same way. A `$$` fence (or a paragraph that is one `$$ ... $$` line) becomes a formula block, while a `$$` nothing closes stays text. A `mermaid` code fence becomes a diagram block, unless the diagram's rules refuse it, when it stays a code block; one that passes them but still can't be drawn is refused, as is a save holding more than 10 new diagrams. A Markdown image is refused, since an image is a block.

A text holds at most 1 MiB of UTF-8, within its field's own limit, and a text sent as Markdown at most 64 KiB.

A body's `target` names whose it is by its `kind` and `id`. The store's home is `{ "kind": "store" }`, with the store's id as `id` or none.

A body's blocks each carry an `id`, which [`read_body`](/merchant-mcp/tools/read_body) answers and which stays the same across writes. To change a few blocks, [`edit_body`](/merchant-mcp/tools/edit_body) takes `edits` (`update`, `insert`, `move` or `delete` a block by its id), applied in order and landing together, instead of sending the whole body to [`set_body`](/merchant-mcp/tools/set_body). It checks the result as `set_body` does, and refuses an edit over a body that changed since `from` was read with a `conflict` whose `context.path` and `context.reason` name the argument and what it takes: read the body again and redo the edits. `from` and `live` take the body's `asset.id`, never its `attachment.id`.

## Writes and retries

Most writes take no idempotency key. Two take one of their own in their arguments:

- [`record_order`](/merchant-mcp/tools/record_order) takes `source_key`, your own id for the sale. Only when you sent a `source_key` is a retry safe: send the same one again. A `conflict` with `{ "field": "source_key", "current": "<order id>" }` means the first call landed, and `current` names its order. The key is checked before the order's fields, so the conflict comes back even when the customer, the currency or a line changed since. When the resend's arguments differ from the first call's, read the order `current` names with [`get_order`](/merchant-mcp/tools/get_order) to check it is the same sale.
- [`record_portfolio_event`](/merchant-mcp/tools/record_portfolio_event) takes `idempotency_key`, your own key for the event. A retry with the same key and the same arguments answers the event already recorded. The key belongs to the portfolio: the same key on the same portfolio with different arguments is a `conflict` with `{ "field": "event", "current": "<event id>" }`, and on another portfolio it records a new event.

Without a key, when a write fails or its answer is lost, read the state back before trying again, so the write doesn't land twice.

## Bulk

[`bulk`](/merchant-mcp/tools/bulk) runs one tool on up to 50 items in a call. It takes:

- `accessor`: which tool to run, by the name in the first column below (camelCase, not the tool's name).
- `items`: each item's arguments, as the tool alone takes them.

```json
{
  "accessor": "unpublishProduct",
  "items": [
    { "product": { "id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80" } },
    { "product": { "slug": "spring-workshop" } }
  ]
}
```

Each item needs the scope of the tool it runs. `bulk` is listed while the connection holds the scope of any of them.

The answer is `results`, one per item in order: `{ "outcome": "done" }`, or `{ "outcome": "refused", "error": { "code": "...", "detail": { ... } } }`. A refused item doesn't fail the call: the call succeeds, and its first text says how many were refused, as in "1 of 2 items refused.".

| `accessor` | Runs |
| --- | --- |
| `publishProduct` | [`publish_product`](/merchant-mcp/tools/publish_product) |
| `unpublishProduct` | [`unpublish_product`](/merchant-mcp/tools/unpublish_product) |
| `discontinueProduct` | [`discontinue_product`](/merchant-mcp/tools/discontinue_product) |
| `reinstateProduct` | [`reinstate_product`](/merchant-mcp/tools/reinstate_product) |
| `unlistProduct` | [`unlist_product`](/merchant-mcp/tools/unlist_product) |
| `relistProduct` | [`relist_product`](/merchant-mcp/tools/relist_product) |
| `deleteProduct` | [`delete_product`](/merchant-mcp/tools/delete_product) |
| `publishEntry` | [`publish_entry`](/merchant-mcp/tools/publish_entry) |
| `unpublishEntry` | [`unpublish_entry`](/merchant-mcp/tools/unpublish_entry) |
| `deleteEntry` | [`delete_entry`](/merchant-mcp/tools/delete_entry) |
| `publishPage` | [`publish_page`](/merchant-mcp/tools/publish_page) |
| `unpublishPage` | [`unpublish_page`](/merchant-mcp/tools/unpublish_page) |
| `deletePage` | [`delete_page`](/merchant-mcp/tools/delete_page) |
| `deleteAsset` | [`delete_asset`](/merchant-mcp/tools/delete_asset) |
| `archiveDiscount` | [`archive_discount`](/merchant-mcp/tools/archive_discount) |
| `restoreDiscount` | [`restore_discount`](/merchant-mcp/tools/restore_discount) |
| `deleteDiscount` | [`delete_discount`](/merchant-mcp/tools/delete_discount) |
| `disableLicense` | [`disable_license`](/merchant-mcp/tools/disable_license) |
| `enableLicense` | [`enable_license`](/merchant-mcp/tools/enable_license) |
| `recordLicense` | [`record_license`](/merchant-mcp/tools/record_license) |
| `hideReview` | [`hide_review`](/merchant-mcp/tools/hide_review) |
| `unhideReview` | [`unhide_review`](/merchant-mcp/tools/unhide_review) |

## Uploading files

A file is uploaded one of two ways:

- **In the call**, for a file up to 2 MiB: [`create_inline_upload`](/merchant-mcp/tools/create_inline_upload) takes what `create_upload` takes, with the file's bytes as `data` in place of its size in `bytes`, and answers the file, already `ready`. It needs no request outside MCP, so it works for a client that can't reach the internet on its own.
- **Through an upload URL**, for a larger file or a client that can send its own HTTP requests: three steps, below. The bytes never pass through the MCP server.

`data` is base64 as in [bytes in arguments](#bytes-in-arguments). Past 2 MiB it is `invalid`; a call past the request body limit in [limits](/merchant-mcp/limits#sizes) is refused before it reaches the store.

Through an upload URL:

1. **Step 1**

   Call [`create_upload`](/merchant-mcp/tools/create_upload) with the file's `name`, `mime`, size in `bytes` and, optionally, its `enforcement`. It reserves the file and answers it as `asset`, with `upload`: the `url` to send the bytes to, the `method` (`PUT`), the `headers` to send and `expires_at`.
2. **Step 2**

   Send the bytes to `upload.url` with a `PUT` and every header in `upload.headers`, within 15 minutes. This is a plain HTTP request, so the client needs to make one outside MCP. Any other header it sends is dropped when the upload completes.
3. **Step 3**

   Call [`complete_upload`](/merchant-mcp/tools/complete_upload) with the `asset`. To give up instead, call [`cancel_upload`](/merchant-mcp/tools/cancel_upload).

A file is up to 5,115 MiB through an upload URL. `enforcement` decides, either way, who may reach its bytes:

- `signed`, the default: served only through links that expire, the one for anything you sell. It takes any media type.
- `public`: anyone with its link may load it, such as images on your pages. It takes only images (not SVG), video, audio and PDFs.

[`move_asset`](/merchant-mcp/tools/move_asset) with the other `enforcement` changes it later.

To swap a file's bytes and keep where it is used, upload the new bytes either way, then call [`replace_asset`](/merchant-mcp/tools/replace_asset) with the file as `asset` and the new one as `upload`. A link to a file hosted elsewhere, such as an external video, is made with [`create_asset`](/merchant-mcp/tools/create_asset) instead.

Neither `create_upload` nor `create_inline_upload` takes a key: after a failure, look for the file with [`list_assets`](/merchant-mcp/tools/list_assets) before trying again.

## Bytes in arguments

A small image, such as the store's icon in [`set_store_icon`](/merchant-mcp/tools/set_store_icon) or the business's logo in [`set_organization_logo`](/merchant-mcp/tools/set_organization_logo), goes in the arguments themselves, as does a small file's `data` in [`create_inline_upload`](/merchant-mcp/tools/create_inline_upload), as base64: the standard alphabet with padding, no line breaks and no `data:` prefix. Anything else is `invalid`.

## Reading files

[`get_asset_url`](/merchant-mcp/tools/get_asset_url) takes the file as `asset` and, optionally, `disposition`: `inline` to view it, or `attachment` to download it.

- A file anyone may open, a link or a public file viewed inline, comes back as its `url`.
- Anything else, a private file or a download asked for as an attachment, comes back inside the result. Sherpo fetches the file and adds it to `content` as an embedded resource, with the `uri` `urn:sherpo:asset:<id>`, its `mimeType`, and the file as `text` for a text file or as base64 in `blob` otherwise. Read the file from there: the answer's `url` serves no one.

```json
{
  "type": "resource",
  "resource": {
    "uri": "urn:sherpo:asset:3c9a1f60-7b2d-4e85-a0c4-6d8e2f1b9a73",
    "mimeType": "text/csv; charset=utf-8",
    "text": "email,product\nada@example.com,Spring workshop\n"
  }
}
```

A file handed back this way is up to 8 MiB. A larger one is a tool error, `invalid`: "The file is larger than 8 MiB, past what a tool result carries."

Source: https://docs.sherpo.io/merchant-mcp/calling-tools/index.mdx
