Read Note
vault_read_noteRead a markdown note by vault-relative path and return its full content or target just properties, outline, or one heading section, with line paging for large notes.
Instructions
Read a markdown note by its vault-relative path. By default returns the full raw content including properties; optional modes return just the properties, just the heading outline, or just one section.
Example: vault_read_note({ path: "Projects/vault-cortex.md" }) Example: vault_read_note({ path: "TASKS.md", outline: true }) Example: vault_read_note({ path: "TASKS.md", heading: "Active" }) Example: vault_read_note({ path: "TASKS.md", heading: "Done", heading_level: 2 }) Example: vault_read_note({ path: "TASKS.md", heading: "Done", start_line: 1, limit: 20 })
When to use: You know the exact path and need a specific note's content. For a large note (a long Kanban board or doc), use outline: true to see its headings and any text sitting above them, then heading: "..." to read just the one section you need. For a note or section too long for one response, page it with start_line and limit to read a window at a time. To check a note's or section's line count, request start_line: 1 with limit: 1 — one line plus the total. Prefer vault_search when you don't know the path. For task status or order on a board, prefer vault_list_tasks; heading mode returns a lane's Markdown. Prefer vault_get_memory for About Me/ files (returns content without properties). To edit a section you've read, use vault_patch_note. To explore what links to this note or what it links to, use vault_get_backlinks and vault_get_outgoing_links.
Behavior: a section spans from its heading to the next heading with the same or a smaller level number (or EOF), so it includes its child headings. Empty headings ("##" with no text) act as boundaries but cannot be targeted; read the parent section or the full note, and edit them via vault_replace_in_note.
Errors:
"note not found" — no note exists at this path; verify it with vault_list_notes
"heading not found" — the message lists the available headings
"ambiguous heading" — multiple headings match; use heading_level to disambiguate, or read the full note (omit heading) when headings share the same level
"outline, heading, and properties_only are mutually exclusive — set at most one"
"heading_level requires a heading" — pass heading with it
"heading cannot be empty" — heading is whitespace only; pass the heading's text
"line paging is not available in outline mode" / "… properties_only mode" — start_line and limit page only a full read or a heading section
"start line past the end" — the message states the line count; resend a start_line within it
'path must end in ".md"' — add the extension to a note's path; read other files (images, .canvas, data files) with vault_read_file
"absolute path blocked" / "path traversal blocked" / "hidden path blocked" — pass a vault-relative path with no dot-prefixed part
"properties block is not valid YAML …" — only properties_only raises it; a full read, outline and heading still work; the error says how to repair it
"ENAMETOOLONG: …" or another filesystem error — the message says what to do
Returns: Raw markdown string (default); JSON object of properties, {} when the note has none (properties_only); JSON outline object, shaped as the outline parameter describes (outline); raw markdown of the section, heading line included (heading). When start_line or limit is given, the result is preceded by a window-metadata text block ("path — lines 1–20 of 250 (continue with start_line: 21)"). Unpaged full reads return the file's exact bytes; heading sections and paged reads use LF line endings. In the outline, bytes at the root is the whole file's size, modified its modification time (ISO 8601), and each heading's bytes the size of the text heading mode returns for that section; an empty heading appears with text: "".
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"path": "<path>"
},
"name": "vault_read_note"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative path to the note, including the ".md" extension (e.g. "About Me/Principles.md"). Use the exact letter case. | |
| limit | No | Maximum lines returned (default: all remaining). | |
| heading | No | Return only this section. Case-sensitive exact match. | |
| outline | No | If true, returns { bytes, modified, leading_callout?, leading_content?, headings } as JSON instead of body content. headings: [{ level, text, bytes }]; leading_callout: { type, title, body } when the note has a top-of-file callout; leading_content: the rest of the body text above the first heading (callout lines excluded) when the note has any. | |
| start_line | No | First line to return, 1-based (default 1). | |
| heading_level | No | Heading level (1-6) for disambiguation when multiple headings share the same text | |
| properties_only | No | If true, returns parsed properties as JSON instead of full note content |