Skip to main content
Glama
aliasunder

Vault Cortex Obsidian MCP Server

by aliasunder
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Write Note

vault_write_note
Destructive

Create a markdown note. Errors if a note already exists at the path unless overwrite is set. Body replaces the entire note content: existing content will be lost unless you include it in body, so do not use this tool for surgical edits to…

Instructions

Create a markdown note. Errors if a note already exists at the path unless overwrite is set. Body replaces the entire note content: existing content will be lost unless you include it in body, so do not use this tool for surgical edits to large files. Properties merge with any existing properties when overwriting (new keys added, matching keys overwritten, keys set to null removed, unmentioned keys preserved); overwriting without properties keeps the existing property values. A new note leaves out keys set to null.

Example: vault_write_note({ path: "Projects/notes.md", body: "# Notes\n\nProject notes here.", properties: { tags: ["project"], type: "project" } }) Example: vault_write_note({ path: "Projects/notes.md", body: "Updated content.", overwrite: true })

When to use: Creating a new note. Set overwrite: true only when you intend to replace an existing note's body. Prefer vault_update_properties for property-only edits (no body round-trip). Prefer vault_update_memory for appending dated entries to About Me/ memory files.

Errors:

  • "note already exists" — set overwrite: true to replace it, or use vault_patch_note or vault_replace_in_note for partial edits

  • "path must end in …" — add the .md extension

  • "cannot write note …: that path is not a file" — a folder already has this name; choose another path

  • "absolute path blocked" / "path traversal blocked" / "hidden path blocked" — use a vault-relative path with no hidden (dot-prefixed) file or folder in it

  • "concurrent write in progress" — another write to this note is in flight; re-read the note and retry

  • "body contains a control character" — body includes a non-printable control byte; remove it before writing

  • "properties block …" — with overwrite: true, the note's properties block can't be read, or a rewrite would lose it; the error says how to repair it

  • "the note would open with a properties block the server cannot keep …" — the note would get no properties (none passed or kept from an overwritten note, or every key set to null), and the body opens with --- lines around text that is invalid YAML, a list, a single value, or a YAML tag, which would become its properties block; pass at least one property, or start the body without --- lines

Obsidian syntax: Body is Obsidian Flavored Markdown (no escaping applied). Watch for: #word = tag (escape with #), [[ = wikilink, %% = comment block. In properties: quote wikilink values ("[[Note]]"), use YAML lists for tags, keep property types consistent (string/number/list mismatches cause silent query failures).

Returns: "Wrote ".

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyYesMarkdown body content — do not include frontmatter fences (---); use the properties parameter instead.
pathYesVault-relative path including the ".md" extension (e.g. "Projects/notes.md"). Parent folders are created as needed. Use the exact letter case; a different case can create a duplicate note or folder.
overwriteNoAllow overwriting an existing note (default: false).
propertiesNoProperties to merge.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.54.13
    • changedInput schema / properties / overwrite / description
      Previous value: -"Allow overwriting an existing note (default: false — errors if file exists)."New value: +"Allow overwriting an existing note (default: false)."
    • changedInput schema / properties / properties / description
      Previous value: -"Optional properties to merge; a null value deletes that key."New value: +"Properties to merge."
  2. Changed1 schema field changedv0.54.9
    • changedInput schema / properties / properties / description
      Previous value: -"Optional properties to merge. New keys are added; existing keys with matching names are overwritten; a null value deletes that key; unmentioned keys are preserved from the existing file."New value: +"Optional properties to merge; a null value deletes that key."
  3. Changed1 schema field changedv0.54.7
    • changedInput schema / properties / path / description
      Previous value: -"Vault-relative path including the \".md\" extension (e.g. \"Projects/notes.md\"). Parent folders are created as needed."New value: +"Vault-relative path including the \".md\" extension (e.g. \"Projects/notes.md\"). Parent folders are created as needed. Use the exact letter case; a different case can create a duplicate note or folder."
  4. Changed1 schema field changedv0.50.0
    • addedInput schema / properties / overwrite / default
      Added value: +false
  5. Addedv0.32.1
  6. Removedv0.32.0
  7. Changed1 schema field changedv0.27.2
    • addedInput schema / properties / overwrite
      Added value: +{
+  "description": "Allow overwriting an existing note (default: false — errors if file exists).",
+  "type": "boolean"
+}
  8. Changed1 schema field changedv0.23.10
    • changedInput schema / properties / path / description
      Previous value: -"Vault-relative path (e.g. \"Projects/notes.md\"). Parent folders are created as needed."New value: +"Vault-relative path including the \".md\" extension (e.g. \"Projects/notes.md\"). Parent folders are created as needed."
  9. Changed2 schema fields changedv0.23.5
    • changedInput schema / properties / body / description
      Previous value: -"Markdown body content (no frontmatter fences)"New value: +"Markdown body content — do not include frontmatter fences (---); use the properties parameter instead."
    • changedInput schema / properties / path / description
      Previous value: -"Vault-relative path for the note"New value: +"Vault-relative path (e.g. \"Projects/notes.md\"). Parent folders are created as needed."
  10. Changed1 schema field changedv0.15.23
    • changedInput schema / properties / properties / description
      Previous value: -"Optional properties to merge. New keys are added; existing keys with matching names are overwritten; unmentioned keys are preserved from the existing file."New value: +"Optional properties to merge. New keys are added; existing keys with matching names are overwritten; a null value deletes that key; unmentioned keys are preserved from the existing file."
  11. Added

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Far exceeds what the annotations (destructiveHint, readOnlyHint, idempotentHint) convey: it spells out that existing content is lost unless re-supplied, the precise properties merge algorithm (add/overwrite/null-removes/unmentioned-preserved), concurrency behavior, and an eight-entry error catalog with remedies. The destructive and non-idempotent profile is fully explained in operational terms.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded (purpose, then two examples, then when-to-use, errors, syntax, returns) and the sections are legible. The error catalog is long, but each entry encodes a distinct failure mode and remedy for a destructive write, so most of it earns its place rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything an agent needs: creation vs. overwrite semantics, property merge behavior, Obsidian syntax pitfalls (tag/wikilink/comment escaping, YAML typing), and the return value ("Wrote <path>") despite no output schema. Nothing material for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema lacks: the merge semantics of the nested `properties` object and the exact consequence of toggling `overwrite`. It does not redefine path/body, so it clears the baseline without being exhaustive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Create a markdown note") and immediately distinguishes itself from partial-edit siblings by stating that body replaces the entire content. An agent can tell it apart from vault_patch_note, vault_replace_in_note, and vault_update_properties without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit "When to use" section, names the exact condition for overwrite: true, and routes to alternatives (vault_update_properties for property-only edits, vault_update_memory for dated appends, vault_patch_note/vault_replace_in_note for partial edits). When-not and alternative conditions are both stated rather than implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools