notes-update
Update a note: edit its content, move it to a different folder (set container_id, or null for the inbox), archive/favorite it, or change its tags. This is the tool for moving notes between folders; there is no separate move tool. Required: id (integer). Optional content (exactly one body-mutation mode at a time): title, body (full replace), append_body (appends to existing body), insert_after + insert_body (insert text immediately after a unique anchor snippet from the existing body), insert_before + insert_body (insert before a unique anchor), replace_find (+ optional replace_with) (replace a unique snippet; omit replace_with entirely to delete the snippet). Markdown-structure ops (heading/section/checklist aware — safer than eyeballing a unique snippet on long notes): replace_section + section_body (replace everything UNDER a heading, keeping the heading line); append_to_section + section_body (add content at the END of a section — the safe 'insert under heading' when you don't know its last line); rename_heading + new_heading (rename a heading in place, preserving its level unless new_heading carries its own '#'); check_item / uncheck_item (tick/untick a checklist item by its text, e.g. '- [ ] ship it'). Headings and checklist items must each match exactly one line. Anchor and find snippets must match exactly once; include enough surrounding context to disambiguate. Also optional: summary, source_url. Freshness: verified (boolean — pass true to mark the note re-confirmed as still true right now; only send this after the user has actually confirmed it), review_after (ISO 8601 datetime to time-box the note, or null to clear it). Organization: container_id (move note), archived (boolean — works on your own personal notes and on team notes where you have the editor role; notes in shared containers are owner-only), favorited (boolean). Tags: tag_list (full replace, comma-separated), add_tags, remove_tags. tag_list takes precedence over add_tags/remove_tags. Concurrent edit safety: pass expected_lock_version (the lock_version you saw when you last read the note via notes-get / notes-list / search) whenever you want a stale-write guard. If it doesn't match the current version, the update is rejected with the current state included so you can re-read and re-apply (append_body-only calls are exempt; see expected_lock_version). Surgical edits (append_body / insert_after / insert_before / replace_find) are anchor-based and so don't need expected_lock_version for their body change — but if you also change title / summary / container_id alongside, those fields can still silently overwrite a newer save unless you supply expected_lock_version. Examples: insert under a heading {id: 42, append_to_section: 'Open Questions', section_body: '- Should we ship Friday?'}; replace a section {id: 42, replace_section: '## Status', section_body: 'Shipped 🎉'}; rename a heading {id: 42, rename_heading: 'TODO', new_heading: 'Done'}; tick a checklist item {id: 42, check_item: 'ship it'}; fix a typo {id: 42, replace_find: 'recieved', replace_with: 'received'}; safe full rewrite {id: 42, body: '...', expected_lock_version: 5}. Every edit is recorded as a named, revertable revision attributed to you — use notes-history to see who changed what, and notes-revert to undo a change.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Note ID (required) | |
| body | No | New body content — full replacement. Mutually exclusive with the other body-mutation modes. Pair with expected_lock_version for concurrent-edit safety. | |
| title | No | New title | |
| summary | No | New summary | |
| add_tags | No | Comma-separated tags to add to existing tags (ignored if tag_list is provided) | |
| archived | No | Archive (true) or unarchive (false) the note. Works on your own personal notes and on team notes where you have the editor role; notes in shared containers can only be archived by their owner. | |
| tag_list | No | Full replacement comma-separated tag list (takes precedence over add_tags/remove_tags) | |
| verified | No | Pass true to mark the note re-confirmed as still true as of now (the 'mark verified' affordance). Refreshes verified_at and clears 'stale' status. Only send after the user has confirmed the note is still accurate. | |
| favorited | No | Favorite (true) or unfavorite (false) the note. Personal and team notes. | |
| check_item | No | Text of a checklist item to tick (set to '[x]'). Matched case- and whitespace-insensitively; a leading bullet/checkbox in the text is ignored. Must match exactly one item. | |
| source_url | No | New source URL | |
| append_body | No | Content to append to the existing body. Mutually exclusive with the other body-mutation modes. | |
| insert_body | No | Text to insert. Must be paired with either insert_after or insert_before. Mutually exclusive with the other body-mutation modes. | |
| new_heading | No | New heading text for rename_heading. The original level is preserved unless this carries its own leading '#' markers. | |
| remove_tags | No | Comma-separated tags to remove from existing tags (ignored if tag_list is provided) | |
| container_id | No | Folder (container) id to move the note into; pass null to move it to the inbox (remove it from its folder) | |
| insert_after | No | Anchor snippet from the existing body — insert_body is inserted immediately after the unique occurrence. Anchor must match exactly once; include surrounding context to disambiguate. | |
| replace_find | No | Snippet to find in the existing body. Must match exactly once. Mutually exclusive with the other body-mutation modes. | |
| replace_with | No | Optional replacement for replace_find. Omit it (or pass an empty string) to delete the matched snippet. | |
| review_after | No | ISO 8601 datetime after which the note should be treated as stale (time-boxing), or null to clear it. | |
| section_body | No | The content for replace_section / append_to_section. Required when either is given. | |
| uncheck_item | No | Text of a checklist item to untick (set to '[ ]'). Same matching rules as check_item. | |
| insert_before | No | Anchor snippet from the existing body — insert_body is inserted immediately before the unique occurrence. Anchor must match exactly once. | |
| rename_heading | No | Heading to rename (with or without leading '#'). Pair with new_heading. Heading must match exactly one. | |
| replace_section | No | Heading whose section content should be replaced (with or without leading '#', e.g. '## Status' or 'Status'). Replaces everything under the heading up to the next same-or-higher-level heading, keeping the heading line. Pair with section_body. Heading must match exactly one. | |
| append_to_section | No | Heading to append content to (with or without leading '#'). Adds section_body at the END of that section — the safe way to 'insert under a heading'. Pair with section_body. Heading must match exactly one. | |
| expected_lock_version | No | Optional concurrent-edit guard. Pass the lock_version you saw when you last read the note; if it doesn't match the current version, the update is rejected and you should re-read and re-apply. Checked whenever supplied — covers title, summary, container_id, body, anything else — with one exception: when append_body is the call's ONLY edit, a stale value does not reject (a bare append lands at the end of the current body and can't lose anyone's update). That exemption also means an append is not replay-protected: if you retry an identical append-only call whose response you never saw, the text is appended twice, so re-read with notes-get instead of blind-retrying. Surgical body edits without this param still work and remain anchor-safe; supply it any time you want a stale-write guard for the other fields too. |