Skip to main content
Glama

Update Block

update_block
DestructiveIdempotent

Update the content of a specific block on a page. Blocks are the building sections — hero, features, testimonials, FAQ, etc. You can update text, images, items, CTAs, and layout variant.

Annotations: read-only=false, destructive=true, idempotent=true, open-world=false. Why: Overwrites one section's content or settings on the DRAFT — non-additive, so destructive by the MCP definition; idempotent; closed-world. The live site changes only when the user confirms publish_site; the draft stays editable in the Zarla editor.

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": {
      "site_id": "<site_id>",
      "page_slug": "<page_slug>",
      "block_id": "<block_id>"
    },
    "name": "update_block"
  }
}

Input Schema

NameRequiredDescriptionDefault
ctaNo
imageNo`{ url, alt, focus?, zoom? }` — `focus` is the point of the photo that must stay in view ({x, y} each 0–1 from the left/top; 0.5/0.5 = centre) and `zoom` (1–2) enlarges around it. The object replaces the field whole: sending `url` alone starts the photo centred at 1×; to reframe the current photo, resend its `url` and `alt` with the new `focus`/`zoom`. Both apply on every layout, including the photos behind a hero's text and the call-to-action banner. Values outside the ranges are rejected.
itemsNoRepeating items (features, testimonials, FAQ, etc.)
imagesNoPer-slot images for multi-image layouts (collage, split-duo, bottom-slider) — same shape as `image`, framing included.
contentNoFull content replacement — overrides all above fields
site_idYes
variantNoLayout variant — see list_block_types
block_idYesBlock ID from get_site or get_page (e.g. block-0, block-1)
headlineNo
page_slugYesPage slug
backgroundNoSection background — "default" (page colour) | "alt" (soft) | "primary" (brand colour) | "dark" (dark surface). Null clears it. Choosing a preset also clears any custom colour (a custom colour would otherwise win).
subheadlineNo
background_colorNoCustom section colour as a 6-character hex; overrides the preset. Null clears it. Text adapts automatically.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

B3.4/5.0
Behavior3/5

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

The annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, and the accompanying rationale explains the draft-versus-live semantics. The description itself adds only that a block has multiple editable facets, and notably omits whether unspecified fields are preserved or cleared — critical behavior for a 13-parameter partial-update tool. Useful but thin beyond what the structured fields already provide.

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

Conciseness4/5

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

Two compact sentences, front-loaded with the action and the object, with no filler or repetition. The middle clause defining what a block is earns its place by orienting an agent unfamiliar with the site model.

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

Completeness3/5

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

For a destructive, nested, 13-parameter mutation with no output schema, the description covers identity and scope but leaves out partial-versus-full update semantics and what is returned on success. Annotations supply the safety and draft/live model, and the schema supplies most field detail, so the remaining gap is moderate rather than disqualifying.

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

Parameters3/5

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

Schema description coverage is 69%, so the schema carries most of the load, and the description's field list (text, images, items, CTAs, layout variant) loosely maps to headline/subheadline/image/images/items/cta/variant. It adds no guidance on the interaction between the granular fields and the `content` full-replacement override, nor on the undescribed cta/items/headline/subheadline parameters. Baseline 3 fits given the schema's own detail.

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

Purpose4/5

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

The description gives a specific verb and resource ("Update the content of a specific block on a page") and clarifies the domain object ("Blocks are the building sections — hero, features, testimonials, FAQ"), then enumerates the updatable facets (text, images, items, CTAs, layout variant). It is unambiguous on its own, but it never contrasts itself with the obvious siblings (add_block, remove_block, reorder_blocks), so an agent must infer that boundary from names alone.

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

Usage Guidelines3/5

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

Usage is only implied: "update the content of a specific block" signals modifying an existing block rather than creating one. There is no explicit when-to-use versus when-to-use-something-else, and no statement of prerequisites (e.g. that block_id must come from get_site/get_page — that appears only in the schema). The publish relationship is covered in the annotation notes rather than the description.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.