Skip to content
Agent Abilities for MCPAgent Abilities

Block tools

Version 1.10.0 added three block tools to the built-in catalog. Two read: an agent can find the block types it may use and read one block type’s definition. One writes: it swaps a single block in a post or page without resending the whole page. All three are off until you enable them on the Abilities tab, like every other tool.

Tool Kind Who can call it
List block types (aafm/list-block-types) Read Users who can edit posts
Get block type (aafm/get-block-type) Read Users who can edit posts
Replace block (aafm/replace-block) Write Users with edit access to that post or page

Read-only mode keeps Replace block out of the agent’s tool list, the same as any other write.

List block types

Section titled “List block types”

Lists the block types registered on the site: core, theme and plugin blocks, ACF blocks included. These are block types, not saved reusable blocks. List blocks (aafm/list-blocks) is the tool for reusable blocks.

It takes an optional namespace (the part before the slash, such as core), an optional search matched against the block name and title, and pagination of up to 100 per page (50 by default). Each entry has the block’s name, title, category, description, allowed parents, and whether it is an ACF block and whether it renders on the server. The response also gives the total.

Get block type

Section titled “Get block type”

Reads one registered block type by name, for example core/group. It returns:

  • the title, description and category
  • attributes and supports
  • style variations
  • parent, ancestor and allowed inner block rules
  • the context it uses and provides
  • the block’s own example, if it has one
  • whether it renders on the server

It returns only what the block editor already shows a user who can edit posts: no render callback, script or style handles, or file paths.

For an ACF block it adds an acf section with the field names, types, choices and sub-fields, plus an example block comment that uses the field names as data keys. Image fields take attachment IDs. ACF blocks take name, data and mode attributes.

Replace block

Section titled “Replace block”

Replaces one whole block in a post or page with new block markup. The agent sends the post ID, a path to the block, and the complete markup of exactly one replacement block.

The path counts real blocks only, from 0: the position among the top-level blocks, then among that block’s inner blocks. The blank lines between blocks and any classic HTML between them are not counted, so [2, 0] is the first block inside the third top-level block. An optional expect_block (for example core/group) refuses the write if the block at that path is a different one.

The response returns the updated post, the path and the name of the block that went in, and any content warnings.

What it leaves alone and when it refuses:

  • Other blocks keep their parsed attributes and HTML. Their delimiter JSON may be rewritten in canonical form, the same as the block editor does on every save. For a user who cannot post unfiltered HTML, WordPress sanitizes the whole page on save, the same as that user’s own editor.
  • It refuses, and changes nothing, when the path points at no block, when the markup is not exactly one block, or when the post’s existing block markup does not survive being re-serialized (for example a block with invalid attribute JSON). Update post is the tool for those.
  • It refuses pages owned by Elementor, Divi, Beaver Builder, Avada or Visual Composer, like the other content writes.
  • When WordPress revisions are on, you can restore the change from revision history.

Content warnings

Section titled “Content warnings”

A block write can come back with content_warnings: one row per problem, each with the block name, a stable code and a message the agent can act on. Since 1.10.0 they also flag:

  • a block name with no registered block type (unregistered_block)
  • ACF block data keys that match none of its fields (unknown_acf_field)
  • delimiter attributes that are not valid JSON, which WordPress then ignores (invalid_block_attributes)
  • a blockGap value WordPress skips (block_gap_dropped)
  • a <style> or <script> element removed with its contents (removed_element)

These five are informational. They never refuse a write, even with strict block validation on, so a strict site does not start refusing writes it used to accept. Strict mode still refuses the editor-invalid-content warnings it always did, such as styling that sits in inline CSS instead of block attributes. See Block-markup validation.

For Replace block, warnings and strict-mode refusals cover the whole resulting page, not only the new block.

How attribute text is stored

Section titled “How attribute text is stored”

Plain attribute text that WordPress would only entity-encode, such as an & in an ACF field, is stored as written for users who may post unfiltered HTML. Other users, and any tags inside attribute values, get WordPress’s own sanitizing. Style and script elements are removed with their contents.

Next steps

Section titled “Next steps”