markdown-vault-mcp

Similar Notes

get_similar

Read-onlyIdempotent

Find notes with similar meaning to a given note, ranked by similarity and matching sections, excluding the source note.

Instructions

Find the notes closest in meaning to a given note; returns them ranked by similarity with their closest sections, the note itself excluded.

Needs semantic_search_available from stats. A note whose embeddings are not built yet has no similar notes.

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": "get_similar"
  }
}

Input Schema

Name	Required	Description
`path`	Yes	Path of the note to compare against, such as `"notes/topic.md"`; case-sensitive.
`limit`	No	Maximum notes to return (default 10).
`folder`	No	Only notes in this folder or below, such as `"3-Resources"`; `""` for top-level notes only.
`filters`	No	Frontmatter values to match, all of them, such as `{"type": "resource"}`; any key works and a list field matches when it holds the value. On an OKF bundle, status (stable includes notes with none), stale (`"true"` or `"false"`) and trust_tier filter too.
`chunks_per_file`	No	Maximum sections per note, at least 1; omit for the server default.
`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

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv6.1.0Nov 2, 2026

changedInput schema / properties / chunks_per_file / description

Previous value: -"Maximum sections returned per file (default 2).\nSet to 1 for one best section per file.  Must be >= 1."New value: +"Maximum sections per note, at least 1; omit for the server\ndefault."

changedInput schema / properties / filters / description

Previous value: -"Frontmatter equality filters, ANDed — e.g.\n{\"type\": \"resource\"}. Matched post-hoc against each\ncandidate's full frontmatter, so any frontmatter key works\n(unlike keyword 'search' filters, which are limited to\nindexed_frontmatter_fields). List-valued fields match if\nthe value is among them. On an OKF bundle three keys carry\nOKF semantics, exactly as in 'search': status (\"stable\"\nalso matches notes without a status field), stale\n(\"true\"/\"false\"), and trust_tier."New value: +"Frontmatter values to match, all of them, such as\n`{\"type\": \"resource\"}`; any key works and a list field matches when it holds the\nvalue. On an OKF bundle, status (stable includes notes with none), stale\n(`\"true\"` or `\"false\"`) and trust_tier filter too."

changedInput schema / properties / folder / description

Previous value: -"Restrict results to this folder (exact match or\nsub-folder prefix), e.g. \"3-Resources\". Useful to scope\nlink candidates to one part of the vault.\nUse folder=\"\" for root-level (top-level) documents only."New value: +"Only notes in this folder or below, such as `\"3-Resources\"`; `\"\"` for\ntop-level notes only."

changedInput schema / properties / limit / description

Previous value: -"Maximum number of similar notes to return (default 10)."New value: +"Maximum notes to return (default 10)."

changedInput schema / properties / path / description

Previous value: -"Relative path of the reference document (e.g.\n\"notes/topic.md\"). Case-sensitive."New value: +"Path of the note to compare against, such as `\"notes/topic.md\"`;\ncase-sensitive."

Changed1 schema field changedv5.0.0Sep 15, 2026

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."

Changed3 schema fields changedv4.0.0Aug 26, 2026

addedInput schema / properties / filters

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Frontmatter equality filters, ANDed — e.g.\n{\"type\": \"resource\"}. Matched post-hoc against each\ncandidate's full frontmatter, so any frontmatter key works\n(unlike keyword 'search' filters, which are limited to\nindexed_frontmatter_fields). List-valued fields match if\nthe value is among them. On an OKF bundle three keys carry\nOKF semantics, exactly as in 'search': status (\"stable\"\nalso matches notes without a status field), stale\n(\"true\"/\"false\"), and trust_tier."
+}

addedInput schema / properties / folder

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Restrict results to this folder (exact match or\nsub-folder prefix), e.g. \"3-Resources\". Useful to scope\nlink candidates to one part of the vault.\nUse folder=\"\" for root-level (top-level) documents only."
+}

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

A3.8/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered by structured data. The description adds genuinely new behavior — self-exclusion from results, similarity ranking, per-section grouping, and the embeddings prerequisite — but says nothing about empty-result behavior or ordering ties beyond what the schema's wait_for_pending_writes note implies.

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 what the tool returns, followed by the prerequisite caveat. No redundant restatement of the title or annotations.

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, return values need not be described, and the description covers the prerequisite, the self-exclusion rule and ranking semantics. It leaves minor gaps around failure modes (invalid path, partially built embeddings) and how folder/filters narrow the comparison set.

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 path, limit, folder, filters, chunks_per_file and wait_for_pending_writes are all documented in the schema itself. The description adds no syntax, defaults, or interaction rules beyond the schema, so the baseline 3 applies.

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 names a specific verb and resource ('Find the notes closest in meaning to a given note') and adds output shape ('ranked by similarity with their closest sections, the note itself excluded'). It distinguishes itself implicitly from query-based siblings like search, but never names an alternative explicitly, which keeps it short of a 5.

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 states a concrete gating condition — semantic_search_available must be true per stats, and notes without built embeddings yield no results — which directly informs whether the agent should call this tool at all. It does not, however, contrast the tool with search or query_documents for agents choosing between retrieval strategies.

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