markdown-vault-mcp

Read Note

read

Read-onlyIdempotent

Retrieve full content of any vault document or attachment by path: raw markdown with frontmatter, or base64 binaries with MIME type. Target a specific section by heading or a past revision.

Instructions

Read the full content of a document or attachment by path.

For .md documents: returns content (the full raw file including frontmatter), plus the parsed frontmatter, title, and folder. For attachments (pdf, png, etc.): returns base64-encoded binary content and MIME type. Use 'list_documents(include_attachments=True)' to discover attachment paths. Use 'stats' to see allowed extensions.

Do not guess paths — look them up first via 'search' or 'list_documents'.

To recover the full text of a specific section returned by 'search', pass section=heading (the value from the result's 'heading' field).

Pass revision= (git-backed vaults) to read the note as it stood at that commit — the route back to content a 'write' replaced. Use a write's 'previous_revision', or a sha from 'get_history'. To restore: read again without revision= for a current etag, then 'write' with if_match set to it.

Context cost: every byte returned counts against the LLM's context budget. Reads above MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTES (default 256 KB for .md) or MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MB (default 1 MB for binaries) raise ValueError. For partial markdown reads, pass section=heading (use the heading field from a search() result).

Input Schema

TableJSON Schema

Name	Required	Description
`path`	Yes	Relative path to the document or attachment (e.g. "Journal/note.md" or "assets/diagram.pdf"). Case-sensitive.
`section`	No	When provided, return the whole section whose heading matches section — every paragraph, list, and sub-section from the heading up to the next heading at the same or higher level (case-sensitive; internal whitespace is collapsed before comparison). Pass the ``heading`` value from a ``search`` result unchanged for guaranteed match. ``None`` (the default) returns the whole document. Ignored for non-.md paths.
`revision`	No	Read the note as it stood at that commit instead of on disk (git-backed vaults, .md only). A sha from 'get_history' or a write result's 'previous_revision'. Pass path as the note is named today; renames are followed. Composes with section=.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv5.0.0Sep 15, 2026

addedInput schema / properties / revision

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Read the note as it stood at that commit instead of on\ndisk (git-backed vaults, .md only). A sha from 'get_history'\nor a write result's 'previous_revision'. Pass *path* as the\nnote is named today; renames are followed. Composes with\nsection=."
+}

First observedv3.1.0Jul 8, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes well beyond this by disclosing return types (raw markdown vs base64 binary), context-cost implications, byte-size limits with environment variables, ValueError behavior, and the fact that section= is ignored for non-.md paths. No contradiction with annotations.

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?

The description is front-loaded with the core purpose and organized into clear paragraphs for file types, path discovery, section usage, revision usage, and context cost. It is longer than average but most sentences add value; the only minor issue is some repetition of the section= guidance near the end.

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 tool with three parameters, annotations, and an output schema, the description covers discovery prerequisites, markdown vs attachment returns, section semantics, revision semantics, size limits, and error behavior. Nothing an agent needs to call this correctly is missing.

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

Parameters5/5

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

Although the input schema already covers 100% of parameters, the description adds substantial meaning: section= should receive the heading value from a search result and is case-sensitive with collapsed whitespace; revision= accepts a sha from get_history or previous_revision and follows renames; and path should not be guessed. This meaningfully exceeds the schema descriptions.

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

Purpose4/5

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

The description opens with a specific verb and resource: 'Read the full content of a document or attachment by path.' It clearly distinguishes .md behavior from attachment behavior, but it does not explicitly differentiate itself from sibling read-like tools such as get_context, vault_read, or browse_vault, so it stops short of full sibling differentiation.

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?

The description gives explicit when-to-use guidance: use list_documents(include_attachments=True) to discover attachment paths, use stats for allowed extensions, and do not guess paths but look them up via search or list_documents. It also explains when to use section= and revision=, and how to restore a previous version with write and if_match. This is strong, actionable routing.

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