Write tools

Tools that mutate the vault. Each returns a result describing what was written. The same business rules as the CLI apply (append-only notes, auto-logged project state, the project cap).

Every write is verified

A tool result that only said “success” could not be told apart from a write that silently never landed — which over a remote connection is exactly how a lost note goes unnoticed. So every write tool re-reads its target before answering, and the result carries the evidence:

{
  "path": "journal/2026/daily/2026-08-26.md",
  "message": "Logged to journal/2026/daily/2026-08-26.md",
  "verification": {
    "verified": "content",
    "bytes_written": 412,
    "content_hash": "84bc0919e867576f",
    "appended_tail": "- **09:14**: baseline sweep finished\n"
  }
}

If the target cannot be read back, the tool returns an error rather than a success. The wording says the write is unverified, not failed: it may still have landed, so the right response is to re-read the note, not to blindly repeat the write.

The appended tail

appended_tail is scoped to the section the write targeted, not to the last bytes of the file. append_to_log and start_action both write into ## Logs, so that is the section you get back. (start_unplanned_action also logs, but it rewrites the project map in the same commit and so verifies as a whole-file rewrite — its appended_tail is null.)

The distinction matters because ## Logs is not always last. Cuaderno pins the effective daily template’s last ## section to the bottom of the note — for the built-in template that is ## Logs, but a custom .cuaderno/templates/daily.md ending in, say, ## Reflection keeps Reflection last and leaves the log line in the middle of the file. Reading the end of the file would then show you Reflection’s text while claiming to be the line that landed.

If the section cannot be located — an unparseable note, a ## Logs heading that is missing or duplicated — the field is null. The write is still verified by bytes_written and content_hash; only the extra evidence is withheld, because a window over the wrong bytes is worse than no window.

The content hash

content_hash is the same non-cryptographic xxh3-64 fingerprint (16 lowercase hex characters) the index uses for change detection, so a client can recompute it over a note it has read and compare. Two uses in practice:

• confirm a note is byte-identical to the one the server saw;
• notice a no-op. update_project_state with a state that already matches deliberately writes nothing and still reports success — an unchanged content_hash across two calls is how you tell.

It is a change detector, not tamper evidence: it does not defend against someone who also chooses the content.

Logging, capture, triage

Evidence

Projects, actions, milestones, waiting-on

Commitments and tracking

Frontmatter

Daily, weekly, and monthly sections

Notes

• append? defaults to replacing the section; set it true to append instead.
• Dates are YYYY-MM-DD; week-scoped tools accept any day in the target week, and month-scoped tools accept any day in the target month.
• vars? is an optional name -> value map supplying values for a custom template’s [variables.prompt] placeholders — the MCP analogue of the CLI’s repeatable --var name=value. Omitting a required prompted variable fails with an “unresolved prompts” error. See Creation and lifecycle tools for the full list of templated tools that accept it.
• See also: Creation and lifecycle tools, JSON output.