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

markdown-vault-mcp

by pvliesdonk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Table of Contents

get_toc
Read-onlyIdempotent

Retrieve the heading outline of a Markdown note or all notes in a folder, with optional heading-depth and note limits.

Instructions

Return the heading outline of a note, or of every note under a folder.

For a note: a list of {heading, level}, the title first as level 1. For a folder: {path, notes, truncated}, each note with its path, title and headings.

Input Schema

NameRequiredDescriptionDefault
pathYesA note path ending in .md, such as `"a/b.md"`, or a folder, such as `"a/b"`.
max_levelNoDeepest heading level to keep, such as 2 for H1 and H2; omit for all. The title always stays.
max_notesNoFolders only: notes to include, first by path (default 200); truncated is true when more exist.
wait_for_pending_writesNoWait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv6.1.0
    • changedInput schema / properties / max_level / description
      Previous value: -"Drop headings deeper than this level (e.g. 2 keeps\nH1-H2); must be >= 1. The synthetic H1 title always survives.\nDefault None returns all levels."New value: +"Deepest heading level to keep, such as 2 for H1 and H2; omit for\nall. The title always stays."
    • changedInput schema / properties / max_notes / description
      Previous value: -"Folder mode only — cap on distinct notes (default 200,\nmust be >= 1). When more notes match, the first max_notes (by\npath) are returned and 'truncated' is True."New value: +"Folders only: notes to include, first by path (default 200);\ntruncated is true when more exist."
    • changedInput schema / properties / path / description
      Previous value: -"Note path (\"a/b.md\") or folder prefix (\"a/b\")."New value: +"A note path ending in .md, such as `\"a/b.md\"`, or a folder, such as `\"a/b\"`."
  2. Changed1 schema field changedv5.0.0
    • changedInput schema / properties / wait_for_pending_writes / description
      Previous value: -"When True, wait until recent\ndocument mutations are applied to the index\nbefore answering. Default False answers from the current\nindex; inspect '_meta.index_stale' to tell whether a write was\nstill in flight. Bounded by a server timeout (default 60s)."New value: +"Wait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false."
  3. Changed1 schema field changedv4.0.0
    • changedInput schema / properties / wait_for_pending_writes / description
      Previous value: -"When True, wait until recent\nwrite/edit/delete/rename operations are applied to the index\nbefore answering. Default False answers from the current\nindex; inspect '_meta.index_stale' to tell whether a write was\nstill in flight. Bounded by a server timeout (default 60s)."New value: +"When True, wait until recent\ndocument mutations are applied to the index\nbefore answering. Default False answers from the current\nindex; inspect '_meta.index_stale' to tell whether a write was\nstill in flight. Bounded by a server timeout (default 60s)."
  4. First observedv3.1.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already cover readOnly/idempotent/non-destructive, so the description's added value is in behavior: folder results include a truncated flag, note results lead with the title as level 1. It does not mention the index_stale behavior that wait_for_pending_writes implies, but the mode-dependent shape disclosure is genuinely useful context.

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 short sentences, front-loaded with the core operation, then a compact breakdown of the two result shapes. No filler or repetition.

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 and full schema coverage, the description only needs to frame the two modes, which it does. The main omission is any note about index freshness or when to prefer this over read, but nothing required to call it correctly is missing.

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% and each parameter is documented with examples and defaults, so the schema does the heavy lifting. The description adds nothing parameter-specific beyond the schema, which is the expected baseline at full coverage.

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 ('Return the heading outline of a note, or of every note under a folder') and cleanly distinguishes itself from read/list_documents by naming the outline concept. An agent can tell what this produces 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 Guidelines3/5

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

Usage is implied by the operation — you call it when you want a structural outline rather than full content — but there is no explicit when-to-use/when-not or routing to siblings like read or list_documents. The two modes (note vs folder) are clarified, which is the strongest guidance present.

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