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 new markdown note at a vault path or fully replace an existing note's body and properties when overwrite is enabled. Use for complete writes, not partial edits.

Instructions

Create a markdown note. Errors if a note already exists at the path unless overwrite is set. Body replaces the entire note content — this is a full write, not a partial edit. Properties are passed separately and merged with any existing properties when overwriting (new keys added, matching keys overwritten, keys set to null removed, unmentioned keys preserved).

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.

Limitation: Writes the entire body. Do not use for surgical edits to large files — existing content will be lost unless you include it in the body parameter.

Errors:

  • "note already exists" — a note already lives at this path; set overwrite: true to replace it, or use vault_patch_note / vault_replace_in_note for partial edits

  • "absolute path blocked" — the path starts at the filesystem root; use a vault-relative path

  • "hidden path blocked" — the path targets a hidden (dot-prefixed) file or folder like ".obsidian/"; hidden paths are not writable, matching Obsidian

  • "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

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: Confirmation message.

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.
overwriteNoAllow overwriting an existing note (default: false — errors if file exists).
propertiesNoOptional 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.50.0
    • addedInput schema / properties / overwrite / default
      Added value: +false
  2. Addedv0.32.1
  3. Removedv0.32.0
  4. 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"
+}
  5. 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."
  6. 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."
  7. 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."
  8. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only cover the safety profile (destructive, non-idempotent, closed-world). The description goes well beyond: it discloses overwrite-gated error behavior, full-body replacement semantics, property merge rules (add/overwrite/null-delete/preserve), five named error strings with recovery guidance, and hidden-path restrictions. This is rich behavioral context the annotations cannot express.

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?

Front-loaded with the core semantic (full write vs. partial edit) and organized into When-to-use, Limitation, Errors, and syntax sections. The two examples and the long error enumeration are useful but make it heavier than strictly necessary; still, every block earns its place for a destructive tool.

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?

For a 4-parameter destructive write with no output schema, the description covers everything an agent needs: overwrite semantics, property merge behavior, failure modes with recovery, path constraints, and the return value ('Confirmation message'). No output schema exists, so return-format detail is not owed.

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 baseline is 3, but the description adds meaning beyond the schema: body is a complete replacement rather than a merge, properties are merged rather than replaced, and the error text for overwrite=false is spelled out. It slightly reinforces rather than extends some schema text, keeping it out of 5 territory.

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?

States a specific verb and resource ('Create a markdown note') and immediately distinguishes itself from partial-edit siblings by declaring 'this is a full write, not a partial edit.' 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?

Explicit 'When to use' section names the condition for overwrite:true and routes two sibling cases away (vault_update_properties for property-only edits, vault_update_memory for appending dated entries). Also names a 'Limitation' telling the agent when NOT to use it for surgical edits.

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