The advanced catalogue

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

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:

{
  "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:

{
  "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. 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.