docmost-mcp-remote

Overview Schema Source Related Servers Discussions Admin

Replace Section

replace_section

Destructive

Replace a specific page section by index using a section hash to prevent overwriting changes, with an optional dry-run diff and automatic snapshot before writing.

Instructions

Replace one section of a page, found with get_page_outline and read with get_section. Pass the section_hash from get_section: if the section changed since, nothing is written. By default the heading is kept and content replaces what is under it, subsections included; with keep_heading=false content replaces the heading too, and an empty content removes the section. The whole body is saved as a snapshot first. The whole body is rewritten from Markdown, so this is refused on pages with formatting Markdown cannot hold, as update_page replace is.

Input Schema

Name	Required	Description
`page`	Yes	Page id, slug id or Docmost page URL.
`index`	Yes	Section index from get_page_outline.
`content`	Yes	New Markdown for the section.
`dry_run`	No	Only show the change as a diff; write nothing.
`keep_heading`	No	Keep the section's heading line.
`section_hash`	Yes	section_hash from get_section.
`drop_formatting`	No	Write even though the page has formatting Markdown cannot hold, which is then removed. Prefer replace_page_json for such pages.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.2.0Oct 27, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond destructiveHint=true: it discloses optimistic concurrency ('if the section changed since, nothing is written'), that a snapshot is taken first, that the body is rewritten from Markdown and may be refused, that empty content deletes the section, and that drop_formatting is lossy. These are exactly the risk facts an agent needs before a destructive write.

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?

Front-loaded with the core action and its locator, then layered with constraints; every sentence carries decision-relevant content and none is filler. It is dense and slightly run-on in the middle clauses, but no sentence could be dropped without losing a behavior.

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

Completeness5/5

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

For a 7-parameter destructive mutation with an output schema already defined, the description covers the write path, safety protections, refusal conditions, and the escape hatches (dry_run, drop_formatting). Nothing an agent needs to call this correctly is missing.

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; the description adds real meaning on top by explaining section_hash as a staleness guard, keep_heading default behavior including subsection scope, and the empty-content deletion case. page and index are left to the schema, which is fine given full coverage.

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?

States a specific verb and resource ('Replace one section of a page') and immediately scopes it against siblings by naming get_page_outline, get_section, update_page replace, and replace_page_json. An agent can tell exactly which tool this is and where it sits in the workflow.

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

Usage Guidelines5/5

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

Explicitly prescribes the read path (outline -> get_section -> section_hash) and names the alternative for unsupported pages ('Prefer replace_page_json for such pages', restated as 'refused ... as update_page replace is'). Both the when-to-use prerequisites and the when-to-use-something-else case are covered.

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

Deploy Server