markdown-vault-mcp

Read Note

read

Read-onlyIdempotent

Read a note's text, frontmatter, and etag, or an attachment's bytes as base64. Optionally return a single heading section or a past revision by commit SHA.

Instructions

Return a note's text, frontmatter and etag, or an attachment's bytes as base64.

Look paths up with search or list_documents first rather than guessing them.

Input Schema

Name	Required	Description
`path`	Yes	Path in the vault, such as `"Journal/note.md"` or `"assets/diagram.pdf"`; case-sensitive.
`section`	No	A heading, such as the heading field of a search result; returns that section and its sub-sections instead of the whole note. Notes only.
`revision`	No	A commit SHA from get_history or from a write result's previous_revision; returns the note as it stood then, without an etag. Pass path as the note is named today. To restore that text, write it with the etag of a read without revision.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv6.1.0Nov 2, 2026

changedInput schema / properties / path / description

Previous value: -"Relative path to the document or attachment\n(e.g. \"Journal/note.md\" or \"assets/diagram.pdf\").\nCase-sensitive."New value: +"Path in the vault, such as `\"Journal/note.md\"` or `\"assets/diagram.pdf\"`;\ncase-sensitive."

changedInput schema / properties / revision / description

Previous value: -"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=."New value: +"A commit SHA from get_history or from a write result's\nprevious_revision; returns the note as it stood then, without an etag.\nPass path as the note is named today. To restore that text, write it\nwith the etag of a read without revision."

changedInput schema / properties / section / description

Previous value: -"When provided, return the whole section whose heading\nmatches *section* — every paragraph, list, and sub-section\nfrom the heading up to the next heading at the same or higher\nlevel (case-sensitive; internal whitespace is collapsed before\ncomparison). Pass the ``heading`` value from a ``search``\nresult unchanged for guaranteed match. ``None`` (the default)\nreturns the whole document. Ignored for non-.md paths."New value: +"A heading, such as the heading field of a search result; returns that\nsection and its sub-sections instead of the whole note. Notes only."

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.2/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavior beyond that: attachments come back base64-encoded, and revision-based reads omit the etag — a subtle but consequential detail for callers planning a follow-up write.

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 sentences, front-loaded with the return contract before the path-lookup caveat. Zero filler and no restatement of the tool name or title.

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?

With an output schema present, the description does not need to explain return shapes, and it correctly focuses on the return contract and path discovery. Minor gaps remain around error behavior for missing paths and any size limits on base64 attachment reads.

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 description coverage is 100%, so the schema already explains path casing, section-as-heading, and the revision/SHA-without-etag workflow. The description adds little parameter-level meaning beyond noting that etag appears only in the non-revision case, so the baseline 3 applies.

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?

The description states a specific verb ('Return') and enumerates exactly what comes back: note text, frontmatter, etag, or attachment bytes as base64. That dual note/attachment coverage plus the explicit return payload lets an agent distinguish this from write, edit, append, or search without opening the schema.

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

Usage Guidelines4/5

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

It gives explicit routing advice for the path-resolution problem: 'Look paths up with search or list_documents first rather than guessing them.' However, it is silent on when to choose this over the sibling 'vault_read', which appears to be a close analogue, and gives no guidance on when not to read (e.g., huge attachments).

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