update_section
Replace content under a specific heading on a Notion page by providing heading text and new markdown. The section extends from that heading to the next boundary, allowing targeted updates.
Instructions
DESTRUCTIVE — no rollback: this tool deletes blocks in the section, then writes new blocks. If the write fails mid-call, the section is left partially or fully emptied; for most sections the heading anchor is deleted, so a retry can fail with "heading not found." For irreplaceable sections, duplicate_page the target first so you have a restore point.
Update a section of a page by heading name. Finds the heading, replaces everything from that heading to the next section boundary. For H1 headings, the section extends to the next heading of any level. For H2/H3 headings, it extends to the next heading of the same or higher level. Include the heading itself in the markdown. If the section starts at the first block, the replacement markdown must start with the same heading type so following sections stay in place. With preserve_heading:true, the existing heading block ID, text, type, comments, and toggleable state are preserved, but the section body blocks and existing toggleable-heading children are still destructively replaced; replacement markdown is treated as body-only, and a leading matching heading is stripped for compatibility. More efficient than replace_content for editing one section of a large page.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | Preview validation and planned effect without mutating Notion. Default false. | |
| heading | Yes | Heading text to find (case-insensitive) | |
| page_id | Yes | Page ID | |
| markdown | Yes | Replacement markdown including the heading | |
| preserve_heading | No | Preserve the existing heading block and replace only the section body. Default false. |