Advanced catalogue

search_operations

read

Search API operations

Copy page

Find the partner API operation that does what you need, and the exact arguments it takes, before running it through an executor.

Overview

Searches every Sign Customiser partner API operation by keyword, resource family, verb class or required scope, and returns each match stable operation id, summary, required scope, whether it mutates, its parameter and request-body schema, its response schema and a documentation link. It is the discovery step before any execute_read, execute_create, execute_update or execute_delete call, because those take an operation id and nothing else identifies one. It changes nothing and requires the mcp:advanced scope.

Permission

Needs no permission beyond a connected store.

Only visible to a connection grantedmcp:advanced. See theadvanced catalogue guide.

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A merchant has connected this store and approved mcp:advanced.
Either a query, or at least one of the resource, verb_class and scope filters. An unfiltered empty query is refused rather than answered with an arbitrary page.

Arguments

querystring

Words to match against operation ids, summaries, paths and descriptions. Matches are ranked, and an operation matching no word is left out rather than padded in.

resourcestring

Restrict to one resource family, which is the first path segment after /api/v3 — for example customisers, orders, webhook-subscriptions.

verb_classstring

Restrict to one class of operation. read covers every GET and every validation-only operation; the other three name the executor that runs them. Closed set.

One of: read, create, update, delete

scopestring

Restrict to operations requiring one /api/v3 scope. Closed set of 13 values.

One of: customisers:read, customisers:write, pricing:read, pricing:write, products:read, products:write, orders:read, orders:write, quotes:read, webhooks:read, webhooks:write, store:read, analytics:read

limitinteger

How many matches to return, 1 to 50. Defaults to 10. Each match carries full schemas, so a large page is a large response.

Result

Up to limit matches, highest relevance first, each carrying the operation id an executor takes, the scope it needs, the executor that owns it, its schemas and its documentation URL. total_matches and truncated say whether the page is all of them.

request_idstringalways present

The API request id, for support.

storeobjectalways present

The Store this connection resolved to.

store.idinteger

store.namestring

operationsarray of objectalways present

The matches, highest relevance first.

operations[].operation_idstring

The id an executor takes.

operations[].summarystring

One line.

operations[].resourcestring

operations[].verb_classstring

One of: read, create, update, delete

operations[].executorstring

The tool that runs this operation.

operations[].scopestring

The /api/v3 scope the connection also needs. mcp:advanced alone authorises nothing.

operations[].idempotencystring

Whether the operation requires, accepts or refuses an idempotency_key.

One of: none, optional, required

operations[].destructiveboolean

operations[].open_worldboolean

True when the operation reaches beyond the store own data.

operations[].dry_run_operation_idstring

The validate twin a dry run reaches, or null where the operation has none.

operations[].docs_urlstring

total_matchesintegeralways present

How many operations matched, before the page limit.

truncatedbooleanalways present

True when total_matches is larger than this page.

Error cases

insufficient_scope

The connection was approved without mcp:advanced. Ask the merchant to reconnect and approve the advanced tools.

required

Neither a query nor a filter was sent. Send at least one.

validation_failed

A resource family the API does not have. The error repeats every family in allowed_values. A verb_class or scope outside its published enum is refused earlier still, as a JSON-RPC -32602 naming the property.

Find the font-tier operations no curated tool covers

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_operations",
    "arguments": {
      "query": "font tier",
      "verb_class": "create",
      "limit": 1
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "operations": [
        {
          "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/"
        }
      ],
      "total_matches": 3,
      "truncated": true
    }
  }
}

A resource family the API does not have (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_operations",
    "arguments": {
      "resource": "unicorns"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The request could not be completed.",
        "recovery": "Correct every field listed in errors, using its pointer to locate the value and allowed_values where one is given, then call the tool again.",
        "allowed_values": [
          "customisers",
          "orders",
          "products"
        ]
      }
    }
  }
}