update_doc_section
Replace a single section of a workspace's doc body, identified by its heading text. The targeted edit complement to update_doc (full replacement) and append_doc_section (append-only at the end). Use this when the agent maintains a recurring section (e.g., a 'Status' block in a launch-prep doc, an 'Outcomes' block in a meeting note) and only needs to refresh that one piece. Without it, agents are forced into 'GET → splice → PUT' which costs tokens, costs latency, and races against any concurrent human edit elsewhere in the doc (last-write-wins clobbers). Section semantics: the FIRST heading whose plain text matches heading exactly (case-sensitive on trimmed text) is found, and everything from that heading up to the next heading at the same OR shallower level is replaced. So a ## Outcomes section ends at the next ## … or # …; nested ### … subsections stay part of the replaced range. Returns 404 when no matching heading exists; strict by design so a misremembered heading fails loudly. markdown is the FULL replacement, INCLUDING the heading line: pass it back as-is to keep the heading, change it to rename or rewrite the heading, change the heading level, or omit the heading entirely (collapses the section into the prior one). Empty markdown deletes the section. Same markdown surface as update_doc / append_doc_section (CommonMark + GFM +  images + lone-URL videos (mp4/webm/mov/mkv/m4v) + Mermaid + KaTeX + callouts + SVG + details + cross-refs + @-mentions + URL embeds). Identity / attribution / events / doc-guard all flow through the same writeDocBody path as the other doc endpoints, so @-mentions in the new section fire doc.mention_added for newly-added mentions just like update_doc does. Requires editor role. Multi-surface workspaces optionally accept surface_slug to target a specific doc tab. WARNING — a section runs to the next heading of the SAME OR SHALLOWER level, so targeting the LAST heading (or a lone H1) means its section extends to the END OF THE DOCUMENT and this call replaces everything below it. That has silently destroyed a doc twice (#8196), both times returning success. Call get_doc first and check which headings follow the one you are targeting. Agent writes that would drop most of the doc's blocks are now REFUSED with both block counts; pass allowBlockLoss: true to confirm an intended large deletion.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The workspace slug. Accepts either the bare slug ('my-workspace') or the org-prefixed form ('my-org/my-workspace'). | |
| heading | Yes | Plain text of the heading to find (case-sensitive, trimmed). For `## Outcomes`, pass `Outcomes`. Hash marks and surrounding whitespace are stripped from the comparison automatically by the markdown converter. Use `get_doc` first if you need to enumerate the headings actually present. | |
| markdown | Yes | FULL replacement markdown for the section, including the heading line if you want to keep / rename / restructure it. Empty string deletes the section. | |
| surface_slug | No | Optional doc surface slug for multi-doc workspaces. Omit to target the primary doc surface. | |
| allowBlockLoss | No | Confirm a replacement that removes most of the document. Omit it normally: the call is refused (with the previous and new block counts) when it would destroy the bulk of the doc, which is what a trailing-heading target does. Set true only when the deletion is what you intend. |