Skip to main content
Glama
@cmssy/mcp-server

@cmssy/mcp-server

Official

Patch block content

patch_block_content
Destructive

Apply surgical edits to one string in a block's localized content without resending the full content. Use unique markers to insert, replace a section, or replace the whole value.

Instructions

Apply surgical edits (insert_before/insert_after/replace_section, or replace_all to set the whole string, given the value it replaces) to one string in a block's localized content without re-sending the full content - including a string nested in a list or object, via a dotted fieldPath such as 'tabs.0.label'. Each marker must match exactly once. If the result includes blockWarnings, the saved content violates the workspace block manifest (unknown field, wrong value shape, or a stored block whose type is no longer registered) - correct the content and save again, unless the warning is about a stored block whose type is no longer registered: that one is a manifest problem, so restore or sync the type, or find the block with list_block_usage and migrate or remove it. When the warnings also say when the workspace block manifest was last synced, the field or type may simply be newer than the manifest: if the site's code declares it, keep the content and sync the manifest (cmssy sync-manifest in the site's repo) instead. A block whose type the workspace block manifest does not register is refused unless the page already stores that block - pick registered types from list_block_types.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "pageId": "<pageId>",
      "blockId": "<blockId>",
      "locale": "<locale>",
      "operations": "<operations>"
    },
    "name": "patch_block_content"
  }
}

Input Schema

NameRequiredDescriptionDefault
localeYesLanguage code, e.g. 'en' (see get_site_config)
pageIdYesPage id or slug
blockIdYesContent block instance id (layout blocks not supported)
fieldPathNoString field inside content[locale] to patch (default: 'content'). Dot segments reach a nested string, e.g. 'tabs.0.label' for the first item's label
operationsYesOrdered list of patch operations (applied in order)
expectedVersionNoOptimistic-concurrency guard: the `version` get_page returned

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.73.2
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / expectedVersion / description
      Previous value: -"Optimistic-concurrency guard: the page version you last read"New value: +"Optimistic-concurrency guard: the `version` get_page returned"
    • changedInput schema / properties / fieldPath / description
      Previous value: -"Field inside content[locale] to patch (default: 'content')"New value: +"String field inside content[locale] to patch (default: 'content'). Dot segments reach a nested string, e.g. 'tabs.0.label' for the first item's label"
    • changedInput schema / properties / operations / items / oneOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "html": {
      -        "description": "HTML fragment to insert",
      -        "type": "string"
      -      },
      -      "marker": {
      -        "description": "Unique anchor substring (must match exactly one location)",
      -        "type": "string"
      -      },
      -      "op": {
      -        "const": "insert_before",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "op",
      -      "marker",
      -      "html"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "html": {
      -        "description": "HTML fragment to insert",
      -        "type": "string"
      -      },
      -      "marker": {
      -        "description": "Unique anchor substring (must match exactly one location)",
      -        "type": "string"
      -      },
      -      "op": {
      -        "const": "insert_after",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "op",
      -      "marker",
      -      "html"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "endMarker": {
      -        "description": "Exclusive upper bound (once, after startMarker)",
      -        "type": "string"
      -      },
      -      "html": {
      -        "description": "HTML fragment to replace the section with",
      -        "type": "string"
      -      },
      -      "op": {
      -        "const": "replace_section",
      -        "type": "string"
      -      },
      -      "startMarker": {
      -        "description": "Inclusive lower bound (matches once)",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "op",
      -      "startMarker",
      -      "endMarker",
      -      "html"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "html": {
      +        "description": "HTML fragment to insert",
      +        "type": "string"
      +      },
      +      "marker": {
      +        "description": "Unique anchor substring (must match exactly one location)",
      +        "type": "string"
      +      },
      +      "op": {
      +        "const": "insert_before",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "op",
      +      "marker",
      +      "html"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "html": {
      +        "description": "HTML fragment to insert",
      +        "type": "string"
      +      },
      +      "marker": {
      +        "description": "Unique anchor substring (must match exactly one location)",
      +        "type": "string"
      +      },
      +      "op": {
      +        "const": "insert_after",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "op",
      +      "marker",
      +      "html"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "endMarker": {
      +        "description": "Exclusive upper bound (once, after startMarker)",
      +        "type": "string"
      +      },
      +      "html": {
      +        "description": "HTML fragment to replace the section with",
      +        "type": "string"
      +      },
      +      "op": {
      +        "const": "replace_section",
      +        "type": "string"
      +      },
      +      "startMarker": {
      +        "description": "Inclusive lower bound (matches once)",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "op",
      +      "startMarker",
      +      "endMarker",
      +      "html"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "expected": {
      +        "description": "The field's whole current value as get_page returned it - refused if it changed since",
      +        "type": "string"
      +      },
      +      "html": {
      +        "description": "The field's new value, whole",
      +        "type": "string"
      +      },
      +      "op": {
      +        "const": "replace_all",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "op",
      +      "expected",
      +      "html"
      +    ],
      +    "type": "object"
      +  }
      +]
    • changedInput schema / properties / pageId / description
      Previous value: -"Page id"New value: +"Page id or slug"
    • addedInput schema / required
      Added value: +[
      +  "pageId",
      +  "blockId",
      +  "locale",
      +  "operations"
      +]
  2. First observedv0.73.1

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as a destructive write, and the description adds real behavioral context: markers must match exactly once, blockWarnings signal manifest violations, unregistered block types are refused unless already stored, and replace_all is refused if the value drifted. It does not say whether a multi-operation list is applied atomically, which matters because a mid-list exact-match failure could leave a partial edit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, but the definition is two enormous run-on sentences with stacked parentheticals and a mid-sentence colon whose remediation flow is hard to parse. The extensive manifest-warning troubleshooting dominates the text and would be better as a short pointer or separate guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With six parameters, no output schema, and a destructive edit, the description covers the expected failure modes and warning interpretation well, which is exactly what an agent needs here. The gaps are the atomicity of the ordered operation list and any hint about what the successful response contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description clarifies intent the schema only sketches: replace_all takes the whole current value, markers are unique anchors, and fieldPath reaches strings nested in lists or objects. It adds meaning without re-listing every field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ("Apply surgical edits") on a precisely scoped resource (one string in a block's localized content), enumerates the operation variants, and states the distinguishing property versus re-sending full content. It also names a nested fieldPath form ('tabs.0.label'), so an agent can tell it apart from update_block_content at a glance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear conditions for the two modes (marker-based edits vs replace_all for whole-value replacement) and routes to list_block_types for picking registered types and list_block_usage for finding stored blocks. It never explicitly says when to prefer update_block_content or add_block_to_page instead, which is the main missing routing hint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools