# The advanced catalogue

Reach every /api/v3 operation through the advanced catalogue: searching operations, the four executors, and the safety rules they enforce.

- Source URL: https://www.signcustomiser.com/help/mcp/guides/advanced-catalogue/
- Markdown URL: https://www.signcustomiser.com/help/mcp/guides/advanced-catalogue.md

## Guide

The 39 curated tools cover the workflows merchants actually run. The advanced catalogue covers everything else: all 309 operations of the Sign Customiser partner API, reachable through five tools instead of 309.

It exists because a connector that publishes one tool per REST route is unusable, since the tool list alone would fill an assistant's context before it did any work, and because a connector that hides the rest of the API behind "not supported" is a dead end for anyone whose job needs an operation the curated set left out.

## Turning it on

The catalogue is gated behind one permission, **Use advanced tools** (`mcp:advanced`). A connection that was not granted it does not see the five tools in its tool list at all.

That permission grants no data by itself. It grants reachability. Every operation you run through it still needs the same `/api/v3` scope the operation itself declares, checked against the same connection, so `mcp:advanced` plus **View customisers** can read customisers and cannot write them. Approving it can never widen what a connection may do beyond the sum of the other permissions.

Naming one of the five tools without the permission does not answer "unknown tool". It answers `insufficient_scope` and names the permission to approve, because an assistant that read the tool name in this documentation deserves to be told the connection needs reconnecting rather than that the feature does not exist.

## The five tools

| Tool | What it reaches |
| --- | --- |
| [`search_operations`](/help/mcp/tools/search_operations/) | Finds operations. Changes nothing. |
| [`execute_read`](/help/mcp/tools/execute_read/) | Every `GET`, and every validation-only operation. |
| [`execute_create`](/help/mcp/tools/execute_create/) | Every creating operation. |
| [`execute_update`](/help/mcp/tools/execute_update/) | Every updating operation. |
| [`execute_delete`](/help/mcp/tools/execute_delete/) | Every deleting operation. |

The verbs are separate tools rather than one executor with a `method` argument. A host that shows a user what a tool does, and a directory that reviews what a connector can do, both read the tool's annotations; one tool that is sometimes a read and sometimes a deletion can only be annotated as the worst case, which makes the annotation useless for the other 182 operations.

## Step one is always search

An executor takes an `operation_id` and nothing else identifies an operation. There is no URL argument, no path argument and no HTTP method, so the only way to reach an operation is to have found it:

```json
{
  "name": "search_operations",
  "arguments": { "query": "font tier", "verb_class": "create", "limit": 1 }
}
```

Each match carries everything needed to run it, and to decide whether to:

```json
{
  "operation_id": "createFontTier",
  "summary": "Create a font tier",
  "resource": "customisers",
  "verb_class": "create",
  "executor": "execute_create",
  "scope": "pricing:write",
  "idempotency": "required",
  "destructive": false,
  "open_world": false,
  "dry_run_operation_id": "validateCreateFontTier",
  "docs_url": "https://www.signcustomiser.com/help/api/v3-post-create-a-font-tier/"
}
```

`executor` names which of the four tools runs it. `scope` is the permission it needs. `idempotency` is `required`, `accepted` or `none`. `dry_run_operation_id` names the validation twin, when the operation has one.

Searching is ranked, and an operation matching none of the query words is left out rather than padded in. `total_matches` and `truncated` report what a page left behind, so a narrow page is never mistaken for a small result set.

## Operation ids and the REST reference

`docs_url` on every match points at that operation's page in the [public API reference](/help/api/). The link is derived from the operation's own title by the same rule the reference builds its page slugs with, so a catalogue result and a documentation search result point at the same page rather than at two spellings of it.

That is the join to use when an assistant needs the prose behind an operation: the catalogue gives you the schema, the reference page gives you the worked examples, the error contract and the surrounding guides.

## Safety semantics

Everything the curated write tools enforce, the executors enforce too. Nothing is relaxed because the caller reached the operation a different way.

**Confirmation.** `execute_create`, `execute_update` and `execute_delete` all require `confirm: true`. Without it the call changes nothing and answers `confirmation_required`. The executors cannot judge the consequence of an arbitrary operation, so they ask every time.

**Idempotency.** An operation whose `idempotency` is `required` needs an `idempotency_key`, and a repeat of the same key returns the first result rather than acting twice. A different body under a key already used is a conflict, not a silent overwrite.

**Dry runs.** `dry_run: true` runs the operation's validation twin and writes nothing. The verdict is the one the apply would have reached, and a problem the apply would have raised comes back as the same tool error, so a dry run is a real rehearsal rather than a schema check. 120 of the 127 mutating operations have a twin. The seven that do not are `createOrder`, `createProduct`, `exportOrders`, `resendOrderEmail`, and the three webhook-subscription writes.

**Store scope.** Every operation runs inside the one store the connection is bound to. There is no argument that changes it.

**Bounded results.** Reads paginate exactly as the underlying operation paginates, and a truncated result says so explicitly.

## When to use the curated tool instead

If a curated tool covers what you want, use it. It has a narrower schema, a shorter description, error cases written for that specific operation, and it does not need `mcp:advanced` approved. The catalogue is for the 30 operations no curated tool reaches, and for building something general over the whole surface.