AFFiNE MCP Server

Append Semantic Section

append_semantic_section

Appends a semantic section with a heading and native paragraph, bullet, or callout blocks to an existing AFFiNE document, optionally placing it after a chosen section.

Instructions

Append a semantic section to an existing AFFiNE document by heading title and native block composition.

Input Schema

Name	Required	Description
`docId`	Yes	AFFiNE document id.
`bullets`	No	Bulleted items to append under the new section.
`callouts`	No	Callout blocks to append under the new section.
`paragraphs`	No	Paragraphs to append under the new section.
`workspaceId`	No	AFFiNE workspace id. Omit only when AFFINE_WORKSPACE_ID is configured.
`sectionTitle`	Yes	Heading text for the new semantic section.
`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.
`afterSectionTitle`	No	Optional existing section heading to append after.

Output Schema

Name	Required	Description	Default
`ok`	No
`code`	No
`docId`	No
`error`	No
`noteId`	No
`details`	No
`blockIds`	No
`causeCode`	No
`retryable`	No
`workspaceId`	No
`sectionTitle`	No
`appendedCount`	No
`recoveryGuidance`	No
`sectionHeadingId`	No
`afterSectionTitle`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv3.10.2Oct 27, 2026

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare that this is a non-read-only, non-idempotent, non-destructive mutation. The description adds useful append semantics (heading-based insertion, native block composition), but it does not disclose permissions, duplicate-heading behavior, or side effects beyond what annotations and schema convey.

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?

The definition is a single front-loaded sentence with no filler. It states the action and mechanism immediately, leaving details to the rich schema and annotations.

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?

The tool is moderately complex with eight parameters, full schema coverage, an output schema, and annotations covering mutation safety. The description is minimal but sufficient because the schema handles parameter and return details; only finer behavioral nuances like duplicate-section handling are unaddressed.

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 100%, so all eight parameters are already documented. The description reinforces that sectionTitle and native block composition are central, but it does not add syntax, formatting, or behavioral detail beyond the schema.

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 ('Append') and resource ('semantic section') scoped to an existing AFFiNE document, and notes the heading-title/native-block mechanism. It is clear enough to distinguish from generic block or markdown appends, though it does not explicitly name the sibling alternatives it replaces.

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

Usage Guidelines2/5

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

There is no explicit guidance on when to use this tool instead of append_block, append_markdown, create_semantic_page, or other document-editing siblings. The phrase 'existing AFFiNE document' implies a context but does not state exclusions or routing conditions.

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

Deploy Server