markdown-vault-mcp

Search Vault

search

Read-onlyIdempotent

Find documents in a Markdown vault by exact keywords, semantic meaning, or a combined hybrid approach.

Instructions

Find documents matching a query using full-text or semantic search.

Search the vault. Omit 'mode' for the best mode this vault can serve — hybrid when embeddings are configured, keyword when they are not. Pass mode="keyword" for exact terms, operators, or filenames, where FTS5/BM25 beats fusion. Use mode="semantic" for pure vector similarity.

The 'content' field in each result is a snippet by default, not the full document. Use read(path, section=heading) to retrieve the full text of a specific section.

Input Schema

TableJSON Schema

Name	Required	Description
`mode`	No	"keyword" uses FTS5/BM25 for exact terms. "semantic" uses vector similarity (requires embeddings). "hybrid" fuses both via reciprocal rank fusion — best quality when available. Omit it (the default) to follow the vault's configured DEFAULT_SEARCH_MODE, which ships as "auto": hybrid where embeddings exist, keyword otherwise. Any configured default degrades to "keyword" when it needs embeddings the vault lacks; an explicit "semantic"/"hybrid" still errors when unconfigured.
`limit`	No	Maximum results to return (default 10).
`query`	Yes	Natural language or keyword query string.
`folder`	No	Restrict to documents under this folder path (e.g. "Journal"). Must match a value from 'list_folders'. Use folder="" for root-level (top-level) documents only.
`filters`	No	Filter by indexed frontmatter field values, e.g. {"cluster": "craft", "tags": "pacing"}. Only fields listed in indexed_frontmatter_fields (see 'stats') can be filtered. Multiple filters are ANDed. For list fields (e.g. tags), this checks membership — {"tags": "pacing"} matches any document where "pacing" appears in the tags list. On an OKF bundle three keys carry OKF semantics: status ("draft"/ "stable"/"deprecated"; "stable" also matches notes without a status field), stale ("true"/"false" — stale_after reached), and trust_tier ("unverified"/"machine-confirmed"/ "human-reviewed"); "type" filters normally, e.g. {"type": "Playbook", "stale": "false"}.
`snippet_words`	No	Width of the snippet window in words. Omit to use the server default. Set to 0 to return full chunk content. Use read(path, section=heading) for full section recovery.
`chunks_per_file`	No	Maximum number of sections to return per file (default 2). Set to 1 to get only the top-ranked section per file. Must be >= 1.
`wait_for_pending_writes`	No	Wait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv5.0.0Sep 15, 2026

changedInput schema / properties / filters / description

Previous value: -"Filter by indexed frontmatter field values, e.g.\n{\"cluster\": \"craft\", \"tags\": \"pacing\"}. Only fields listed\nin indexed_frontmatter_fields (see 'stats') can be filtered.\nMultiple filters are ANDed. For list fields (e.g. tags),\nthis checks membership — {\"tags\": \"pacing\"} matches any\ndocument where \"pacing\" appears in the tags list. On an OKF\nbundle three keys carry OKF semantics: status (\"draft\"/\n\"stable\"/\"deprecated\"; \"stable\" also matches notes without\na status field), stale (\"true\"/\"false\" — stale_after\npassed), and trust_tier (\"unverified\"/\"machine-confirmed\"/\n\"human-reviewed\"); \"type\" filters normally, e.g.\n{\"type\": \"Playbook\", \"stale\": \"false\"}."New value: +"Filter by indexed frontmatter field values, e.g.\n{\"cluster\": \"craft\", \"tags\": \"pacing\"}. Only fields listed\nin indexed_frontmatter_fields (see 'stats') can be filtered.\nMultiple filters are ANDed. For list fields (e.g. tags),\nthis checks membership — {\"tags\": \"pacing\"} matches any\ndocument where \"pacing\" appears in the tags list. On an OKF\nbundle three keys carry OKF semantics: status (\"draft\"/\n\"stable\"/\"deprecated\"; \"stable\" also matches notes without\na status field), stale (\"true\"/\"false\" — stale_after\nreached), and trust_tier (\"unverified\"/\"machine-confirmed\"/\n\"human-reviewed\"); \"type\" filters normally, e.g.\n{\"type\": \"Playbook\", \"stale\": \"false\"}."

changedInput schema / properties / wait_for_pending_writes / description

Previous value: -"When True, wait until your recent\ndocument mutations have been applied to the\nindex before answering, so the results reflect those changes.\nUse it right after modifying notes when this read must see\nthem (e.g. right after a document mutation whose\neffect this read should reflect). Default\nFalse answers immediately from the current index — almost\nalways already up to date; inspect the response's\n``_meta.index_stale`` field to tell whether a write was still\nin flight. Bounded by a server timeout (default 60s); on\ntimeout it answers from the current index rather than waiting\nlonger."New value: +"Wait for recent index writes. On timeout, answer from the current index with _meta.index_stale=true. Default false."

Changed5 schema fields changedv4.1.0Aug 30, 2026

addedInput schema / properties / mode / anyOf

Added value: +[
+  {
+    "enum": [
+      "keyword",
+      "semantic",
+      "hybrid"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / mode / default
```
Previous value: -"keyword"New value: +null
```

changedInput schema / properties / mode / description

Previous value: -"\"keyword\" uses FTS5/BM25 for exact terms. \"semantic\" uses\nvector similarity (requires embeddings). \"hybrid\" fuses both\nvia reciprocal rank fusion — best quality when available."New value: +"\"keyword\" uses FTS5/BM25 for exact terms. \"semantic\" uses\nvector similarity (requires embeddings). \"hybrid\" fuses both\nvia reciprocal rank fusion — best quality when available.\nOmit it (the default) to follow the vault's configured\nDEFAULT_SEARCH_MODE, which ships as \"auto\": hybrid where\nembeddings exist, keyword otherwise. Any configured default\ndegrades to \"keyword\" when it needs embeddings the vault\nlacks; an explicit \"semantic\"/\"hybrid\" still errors when\nunconfigured."

removedInput schema / properties / mode / enum

Removed value: -[
-  "keyword",
-  "semantic",
-  "hybrid"
-]

removedInput schema / properties / mode / type
```
Removed value: -"string"
```

Changed2 schema fields changedv4.0.0Aug 26, 2026

changedInput schema / properties / filters / description

Previous value: -"Filter by indexed frontmatter field values, e.g.\n{\"cluster\": \"craft\", \"tags\": \"pacing\"}. Only fields listed\nin indexed_frontmatter_fields (see 'stats') can be filtered.\nMultiple filters are ANDed. For list fields (e.g. tags),\nthis checks membership — {\"tags\": \"pacing\"} matches any\ndocument where \"pacing\" appears in the tags list."New value: +"Filter by indexed frontmatter field values, e.g.\n{\"cluster\": \"craft\", \"tags\": \"pacing\"}. Only fields listed\nin indexed_frontmatter_fields (see 'stats') can be filtered.\nMultiple filters are ANDed. For list fields (e.g. tags),\nthis checks membership — {\"tags\": \"pacing\"} matches any\ndocument where \"pacing\" appears in the tags list. On an OKF\nbundle three keys carry OKF semantics: status (\"draft\"/\n\"stable\"/\"deprecated\"; \"stable\" also matches notes without\na status field), stale (\"true\"/\"false\" — stale_after\npassed), and trust_tier (\"unverified\"/\"machine-confirmed\"/\n\"human-reviewed\"); \"type\" filters normally, e.g.\n{\"type\": \"Playbook\", \"stale\": \"false\"}."

changedInput schema / properties / wait_for_pending_writes / description

Previous value: -"When True, wait until your recent\nwrite/edit/delete/rename operations have been applied to the\nindex before answering, so the results reflect those changes.\nUse it right after modifying notes when this read must see\nthem (e.g. right after a write/edit/delete/rename whose\neffect this read should reflect). Default\nFalse answers immediately from the current index — almost\nalways already up to date; inspect the response's\n``_meta.index_stale`` field to tell whether a write was still\nin flight. Bounded by a server timeout (default 60s); on\ntimeout it answers from the current index rather than waiting\nlonger."New value: +"When True, wait until your recent\ndocument mutations have been applied to the\nindex before answering, so the results reflect those changes.\nUse it right after modifying notes when this read must see\nthem (e.g. right after a document mutation whose\neffect this read should reflect). Default\nFalse answers immediately from the current index — almost\nalways already up to date; inspect the response's\n``_meta.index_stale`` field to tell whether a write was still\nin flight. Bounded by a server timeout (default 60s); on\ntimeout it answers from the current index rather than waiting\nlonger."

First observedv3.1.0Jul 8, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: result content is a snippet by default, not the full document, and read should be used for full sections. It also implies mode fallback behavior without contradicting the annotations.

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?

The description is compact and front-loaded: the first sentence states the core purpose, the second paragraph gives actionable mode guidance, and the third covers the snippet caveat. No sentence is wasted, and the structure guides the agent from broad behavior to invocation details.

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?

Given the rich input schema (100% coverage), the output schema, and the read-only/idempotent annotations, the description is complete enough. It covers the key decision points an agent needs—mode selection and the snippet-versus-full-document distinction—without needing to restate schema details or return values.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description adds decision-oriented meaning for the mode parameter (hybrid when embeddings are configured, keyword when not, semantic for pure vector similarity) and clarifies that content fields are snippets, which helps interpret snippet_words. It does not need to repeat the well-documented schema details.

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 opens with a specific verb and resource: 'Find documents matching a query using full-text or semantic search.' It also clarifies the scope ('Search the vault') and differentiates the tool from read by directing the agent to use read for full document text, which separates search from a sibling retrieval tool.

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 mode-selection guidance: omit mode for the best available mode, use keyword for exact terms/operators/filenames, and use semantic for pure vector similarity. It also tells the agent when to hand off to read for full section text, which is concrete alternative guidance.

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