Advanced catalogue

execute_update

write

Execute API update operation

Copy page

Change anything the partner API can change, including the resources no curated tool covers, one operation per call.

Overview

Runs one updating Sign Customiser API operation, named by the stable operation id search_operations returns, applying a merge patch or a replacement document as the operation defines. It reaches every update operation and nothing else: a create, a delete or a read is refused with the tool that does run it. Every call needs confirm: true, and dry_run: true checks the arguments through the operation validate twin without writing. It requires the mcp:advanced scope plus the write scope the operation itself declares.

Permission

Needs no permission beyond a connected store.

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

Annotations

readOnlyHintfalse

destructiveHintfalse

idempotentHintfalse

openWorldHintfalse

Prerequisites

An operation id from search_operations, and its request_schema.
A merchant has connected this store and approved mcp:advanced plus the write scope that operation requires.
The merchant has agreed to the change: confirm: true is required on every call.

Side effects

Applies the change to the record the path addresses.
A replacement operation discards every member the document previously held that the body does not repeat.

Arguments

operation_idstringrequired

The stable id of the operation to run, from search_operations. It is the only way to name an operation: this tool accepts no URL, no path and no HTTP method.

pathobject

The operation path parameters, by name, exactly as search_operations lists them under parameters.path. An identifier the operation does not address is refused.

queryobject

The query parameters, by name, as search_operations lists them under parameters.query. Only read operations take any; a nested object such as filter is sent as the API expects it.

bodyobject

The JSON request body, matching the operation request_schema from search_operations. It is passed to the API unchanged, so a member the operation does not accept comes back as unknown_field naming its pointer. A GET or a DELETE operation takes no body and refuses one.

confirmboolean

Must be true to apply the change, because this tool can reach every update operation the API has and cannot judge the consequence of one on its own. Without it the call returns a confirmation_required error and changes nothing. A dry run does not need it.

dry_runboolean

When true, the operation validate twin is checked and nothing is written: the result is the same verdict the apply would have reached, and a problem the apply would have raised comes back as the same tool error. Defaults to false.

idempotency_keystring

An optional client-generated key unique to this logical write, such as a UUID. Repeating the call with the same key and the same arguments replays the original result; the route does not require one.

Result

The operation own response data, unchanged, plus the top-level members the patch carried.

request_idstringalways present

The API request id, for support.

storeobjectalways present

The Store this connection resolved to.

store.idinteger

store.namestring

operation_idstringalways present

The operation that ran.

statusintegeralways present

The HTTP status the operation answered with.

dry_runboolean

Present and true when nothing was written.

validboolean

Present and true on a passing dry run. A failing dry run is a tool error carrying the problem the apply would have raised, never a verdict saying false.

verdictobject

What the validate twin reported about the operation.

dataobject

The operation own response data, unchanged.

changed_fieldsarray of string

The top-level members the request body carried. It is what the call asked to change, not a diff: /api/v3 does not publish one.

Error cases

confirmation_required

Send confirm: true, or dry_run: true to check the arguments first.

insufficient_scope

The connection holds mcp:advanced but not the write scope this operation needs.

resource_state_conflict

The record is not in a state this change allows. Read it first with execute_read.

unsupported_value

The id names an operation of another class, or has no validate twin for the dry run that was asked for.

validation_failed

The body does not satisfy the operation request_schema; the errors carry the pointer and allowed_values.

Rename a font tier

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_update",
    "arguments": {
      "operation_id": "updateFontTier",
      "path": {
        "customiser_id": 42,
        "font_tier_id": 3
      },
      "body": {
        "name": "Signature"
      },
      "confirm": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "operation_id": "updateFontTier",
      "status": 200,
      "data": {
        "object": "font_tier",
        "id": 3,
        "name": "Signature"
      },
      "changed_fields": [
        "name"
      ]
    }
  }
}

A create is refused, and named (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_update",
    "arguments": {
      "operation_id": "createFontTier",
      "path": {
        "customiser_id": 42
      },
      "body": {
        "name": "Premium"
      },
      "confirm": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "unsupported_value",
        "title": "Operation belongs to another tool",
        "detail": "The operation createFontTier is a create operation, which execute_update does not run. Call execute_create instead.",
        "recovery": "Send one of the values in allowed_values for the field named by pointer or parameter.",
        "parameter": "operation_id",
        "allowed_values": [
          "execute_create"
        ],
        "owning_tool": "execute_create"
      }
    }
  }
}