Skip to main content
Glama
Sign In
markdown-vault-mcp

markdown-vault-mcp

by pvliesdonk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Write Note

write
Idempotent

Create notes or attachments, or replace an entire file, with parent folders created automatically; returns the stored path and whether it was created.

Instructions

Create a note or attachment, or replace one whole; returns its path and whether it was created.

Use edit for targeted changes and append to add to the end. Parent folders are created as needed.

Input Schema

NameRequiredDescriptionDefault
pathYesPath in the vault, such as `"Journal/note.md"` or `"assets/photo.png"`; the extension decides between note and attachment.
contentNoThe note's Markdown body, without frontmatter.
if_matchNoEtag from read, to replace an existing file; omit for a new file.
frontmatterNoThe note's frontmatter, such as `{"title": "My Note", "tags": ["draft"]}`.
content_base64NoAn attachment's bytes, base64-encoded; for paths not ending in .md.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv6.1.0
    • changedInput schema / properties / content / description
      Previous value: -"Full markdown body for .md files (excluding\nfrontmatter). Ignored for attachments."New value: +"The note's Markdown body, without frontmatter."
    • changedInput schema / properties / content_base64 / description
      Previous value: -"Base64-encoded binary content for attachment\nfiles. Required when path is not ``.md``.\n\n**Context cost:** base64 encoding inflates by ~33%; even a 1 MB\nattachment becomes ~1.3 MB of tokens."New value: +"An attachment's bytes, base64-encoded; for paths not ending\nin .md."
    • changedInput schema / properties / frontmatter / description
      Previous value: -"Optional YAML frontmatter dict for .md files,\ne.g. {\"title\": \"My Note\", \"tags\": [\"draft\"]}.\nIgnored for attachments."New value: +"The note's frontmatter, such as\n`{\"title\": \"My Note\", \"tags\": [\"draft\"]}`."
    • changedInput schema / properties / if_match / description
      Previous value: -"Etag from 'read'; required by default to replace an\nexisting file. A stale etag refuses the write. Omit for new files."New value: +"Etag from read, to replace an existing file; omit for a new file."
    • changedInput schema / properties / path / description
      Previous value: -"Relative path (e.g. \"Journal/note.md\" or\n\"assets/photo.png\"). Extension determines handling."New value: +"Path in the vault, such as `\"Journal/note.md\"` or `\"assets/photo.png\"`; the\nextension decides between note and attachment."
  2. Changed1 schema field changedv5.0.0
    • changedInput schema / properties / if_match / description
      Previous value: -"Optional etag obtained from a previous 'read' call.\nWhen provided, the write only proceeds if the file has not\nbeen modified since that read (optimistic concurrency).\nOmit to write unconditionally."New value: +"Etag from 'read'; required by default to replace an\nexisting file. A stale etag refuses the write. Omit for new files."
  3. Addedv4.0.0

TDQS

A4.2/5.0
Behavior3/5

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

Beyond the annotations it discloses that the call reports whether the file was created and that parent folders are created implicitly. However, the phrase 'replace one whole' signals full-content overwrite while destructiveHint is false, and the description never warns that existing content is discarded or that if_match is the guard against clobbering; that is exactly the kind of context a write tool should surface. The mismatch is a soft tension rather than a flat contradiction, since overwrites may be recoverable via the history siblings.

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

Conciseness5/5

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

Two tight sentences with the create/replace semantics front-loaded and the sibling routing immediately after. Every clause carries information: return values, alternatives, and implicit folder creation; nothing is padded.

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

Completeness4/5

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

An output schema exists, so return values do not need spelling out, and the description covers the create-vs-replace distinction, implicit folder creation, and sibling routing. It is nearly complete for a 5-parameter write tool; the missing piece is a caution about overwriting an existing note without an etag.

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

Parameters3/5

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

Schema coverage is 100%, so path, content, if_match, frontmatter and content_base64 are all already explained, including the extension-decides-note-vs-attachment rule. The description adds no parameter-level meaning beyond that, so the baseline 3 applies; folder auto-creation is behavioral rather than parameter guidance.

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 note or attachment'), plus a second mode ('replace one whole') and the return signal ('its path and whether it was created'). It also names the sibling tools it is not (edit, append), so an agent can separate it from the neighbouring mutation tools without inspecting 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?

Explicitly routes between alternatives: 'Use edit for targeted changes and append to add to the end', which defines both when this tool is the right pick and which siblings cover the cases it does not. The only unstated condition is when an overwrite requires an etag, which the schema itself documents.

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