Use this note when editing JSONHTL notes through MCP tools. It records the safe approach after the 2026-07-04 Ask/deployment note edits exposed two easy mistakes: replacing the block before the intended section, and inserting multiple blocks after the same target in reversed or unexpected order.
• Before editing notes through MCP patch, batch, put, reorder or table_op.
• Before restructuring a note, adding a section, or adding child notes from an agent session.
• When a note edit has gone wrong and you need the known failure modes.
Prefer the smallest safe edit that preserves links and metadata. For simple text changes, use block-ID patching. For structural rewrites, whole-document put is often safer than many live insert/delete operations. For table blocks, use table_op rather than treating table data as text.
1. Read the target note with include_block_ids: true.
2. Use the returned rev as if_rev on patch, batch or put.
3. Treat block_ids as the source of truth. Every heading, paragraph, codeblock, list, and table is its own block.
4. Map the exact block ID to the exact content you intend to change before writing. Do not infer that a heading's block ID is also the paragraph under it.
Use patch or batch replace_block with block_id for one known block. Include patch_meta in the same batch when changing content: increment version and set updated to today's date. After the write, read the note back and verify the edited section, not just the tool status.
get(key, include_block_ids=true)
batch(key, if_rev=rev, ops=[
patch_meta(version=N+1, updated=YYYY-MM-DD),
replace_block(block_id=target_id, block=new_block)
])
get(key) # verifyDo not insert several blocks before or after the same target in one batch unless the tool explicitly guarantees ordering. The safer pattern is either: insert the first block, read back, then insert the next relative to the newly inserted block; or use put with the complete document when adding a whole section. This avoids reversed order such as paragraph-before-heading.
For moving sections, reordering headings, deleting several blocks, or doing mixed insert/delete batches, prefer reconstructing the complete document and using put with if_rev. This mirrors normal file editing and is easier to inspect. Preserve title, created, tags, links, and other metadata; increment version; set updated; then read back.
If you must use batch for structural edits, split risky operations: do deletes and inserts separately, re-read between them, and avoid index-based operations after any mutation because indexes drift. Block IDs are safer than indexes, but even block-ID batches can be hard to reason about when several operations target nearby blocks.
Create the child note first with a complete put. Then update the parent to link it. This keeps the note tree discoverable and avoids partial parent pages with missing child content. If editing an index or parent page, preserve all existing links.
• Read back every changed note.
• Check heading/paragraph order around inserted content.
• Search or visually inspect for stale duplicate text left behind.
• Confirm version and updated metadata changed when content changed.
• Confirm any new note is linked from a parent.
• If a mistake appears, correct it immediately and read back again.
• Replacing the heading-adjacent paragraph by using the wrong block ID.
• Forgetting that headings are blocks, so the paragraph below has a different ID.
• Inserting heading and paragraph after the same block and getting unexpected order.
• Using indexes in a multi-step edit after earlier operations have shifted positions.
• Trusting an ok status without reading the document back.
• Creating a useful child note but not linking it from a parent.
• Fixing a content swap between two blocks by reissuing a full-document put when a targeted reorder (or a second, carefully block-ID-checked batch) would have fixed it — costs block-ID continuity for no reason. See README/lessons for a worked example.
See MCP Tools for tool overview, Workflow - Creating and Updating Notes for creation/linking order, and Avoiding Orphaned Notes for preserving discoverability.
If expected Notes write tools appear to be missing, re-run tool discovery before concluding they are unavailable. In testing, a fresh discovery restored the full Notes toolset (including put, batch, and table_op) without needing a new chat.