AFFiNE MCP Server

Update Block

update_block

Partially update a paragraph, heading, quote, list, or code block by block id, changing only the fields you provide while preserving the block id.

Instructions

Partially update one paragraph, heading, quote, list, or code block while preserving its block id. Omitted fields remain unchanged. Paragraph/heading/quote conversions preserve ids; cross-flavour conversions are rejected.

Input Schema

Name	Required	Description
`text`	No	Replacement block text. Delta arrays preserve inline attributes. For LinkedPage references, set insert to one ASCII space and pass the pageId in reference attributes; visible labels are resolved by AFFiNE. Omit to preserve the current text.
`type`	No	Resulting logical block type.
`docId`	Yes	AFFiNE document id.
`level`	No	Heading level. Only valid when the resulting type is heading.
`style`	No	Resulting list style. Only valid for list blocks.
`blockId`	Yes	Block id to update.
`checked`	No	Todo checked state. Only valid for a list whose resulting style is todo.
`workspaceId`	No	AFFiNE workspace id. Omit only when AFFINE_WORKSPACE_ID is configured.
`expectedRevision`	No	Optional read_doc revision of this primary document. Reject stale content before writing. Covers document content, not workspace metadata; requires all writers to share one MCP server.

Output Schema

Name	Required	Description	Default
`ok`	No
`code`	No
`block`	No
`error`	No
`blockId`	No
`changed`	No
`details`	No
`updated`	No
`previous`	No
`causeCode`	No
`retryable`	No
`recoveryGuidance`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv3.10.2Oct 27, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare this is a non-readonly, open-world, non-idempotent, non-destructive mutation. The description adds important behavioral details beyond that: omitted fields are preserved, block ids are retained, and cross-flavour type conversions are rejected. It does not discuss permissions or concurrency, but expectedRevision is documented in the schema.

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

Conciseness5/5

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

Three sentences, each earning its place. The core operation and scope are front-loaded, followed by partial-update semantics and conversion constraints with no wasted wording.

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 nine-parameter mutation tool with full schema descriptions, annotations, and an output schema, the description covers the essential behavior well: partial updates, id preservation, and conversion restrictions. It could be slightly stronger by explicitly routing agents to append_block/move_block for non-update operations, but it is otherwise complete enough to call correctly.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by clarifying that omitted fields remain unchanged and that only certain type conversions preserve ids while cross-flavour conversions are rejected.

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 states a specific verb and resource scope: partially update one existing paragraph, heading, quote, list, or code block while preserving its block id. This naturally distinguishes it from sibling tools such as append_block, move_block, and delete_block without needing to name them.

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 clearly establishes the in-place partial-update context and notes that omitted fields remain unchanged. It also states a useful exclusion: paragraph/heading/quote conversions are allowed, but cross-flavour conversions are rejected. It does not explicitly name alternatives like append_block or move_block, but the usage context is clear.

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

Deploy Server