Skip to main content
Glama
@cmssy/mcp-server

@cmssy/mcp-server

Official

Update page blocks

update_page_blocks
Destructive

Replace all content blocks on a page, keeping existing content for blocks with matching ids. Surfaces blockWarnings when saved content violates the workspace block manifest so you can fix and resave.

Instructions

Set the full content blocks array on a page (replaces all existing content blocks). Blocks with matching ids keep their existing content when not provided. 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 on the shared draft unless the page already stores that block - compose types that are not deployed yet in target: 'devDraft' and promote once the code ships; 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>",
      "blocks": "<blocks>"
    },
    "name": "update_page_blocks"
  }
}

Input Schema

NameRequiredDescriptionDefault
blocksYesFull array of content blocks to set on the page (replaces all)
pageIdYesPage id or slug
targetNo'draft' (default) writes the shared page draft. 'devDraft' writes YOUR per-user dev draft overlay (owned by the token's user) - use it to compose with block types that are not deployed to the site yet; promote it with promote_dev_draft after the code ships. A dev-draft block sent with only id and type inherits every stored bucket it leaves out (content, settings, style, advanced, shared values, translations, metadata) from your dev draft, else from the shared draft; send an empty object ({}) to clear a bucket.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.73.2
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / pageId / description
      Previous value: -"Page id"New value: +"Page id or slug"
    • changedInput schema / properties / target / description
      Previous value: -"'draft' (default) writes the shared page draft. 'devDraft' writes YOUR per-user dev draft overlay (owned by the token's user) - use it to compose with block types that are not deployed to the site yet; promote it with promote_dev_draft after the code ships."New value: +"'draft' (default) writes the shared page draft. 'devDraft' writes YOUR per-user dev draft overlay (owned by the token's user) - use it to compose with block types that are not deployed to the site yet; promote it with promote_dev_draft after the code ships. A dev-draft block sent with only id and type inherits every stored bucket it leaves out (content, settings, style, advanced, shared values, translations, metadata) from your dev draft, else from the shared draft; send an empty object ({}) to clear a bucket."
    • addedInput schema / required
      Added value: +[
      +  "pageId",
      +  "blocks"
      +]
  2. First observedv0.73.1

TDQS

A4.4/5.0
Behavior5/5

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

Annotations only declare non-read-only and destructive; the description goes well beyond by explaining id-based merge semantics, what blockWarnings mean, the three causes (unknown field, wrong shape, unregistered stored type), and the refusal of unregistered types on the shared draft. That is real operational context an agent could not derive from the annotation pair.

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

Conciseness3/5

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

The first sentence front-loads the essential fact, but the remainder is one dense run-on paragraph with chained semicolons, nested 'unless' clauses, and an aside about manifest sync timing. The warning-handling content is valuable but would scan far better split into short bullets or a separate paragraph.

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?

For a destructive replace-all mutation with no output schema, the description covers mutation semantics, the warning return path, and the dev-draft escape hatch. It stops short of mentioning page-lock behavior or recovery options (e.g., restore_page) that would matter after an accidental full overwrite.

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 adds meaning the schema does not spell out: blocks with matching ids retain stored content when a bucket is omitted, and the draft-vs-devDraft inheritance/promotion workflow is restated in call context. It reinforces rather than merely repeats the target parameter documentation.

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 opening sentence names a specific verb and resource ('Set the full content blocks array on a page') and immediately states the destructive scope ('replaces all existing content blocks'), which separates it from incremental siblings like add_block_to_page or update_block_content. An agent knows exactly what effect the call has without opening the schema.

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?

Provides clear conditional routing: compose not-yet-deployed types in target 'devDraft' and promote after the code ships, and use list_block_types to pick registered types. It does not explicitly say when to prefer this over add_block_to_page/update_block_content for partial edits, leaving that distinction to inference from the 'replaces all' wording.

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