markdown-vault-mcp

Note Context

get_context

Read-onlyIdempotent

Retrieves a Markdown note's metadata, backlinks, outlinks, similar notes, folder neighbors, tags, and conventions in one call, replacing separate lookups when multiple relationships are needed.

Instructions

Return a note's metadata, backlinks, outlinks, similar notes, folder neighbours, indexed tags and applicable conventions in one call.

Use it instead of get_backlinks, get_outlinks and get_similar when you need more than one of them.

Input Schema

Name	Required	Description
`path`	Yes	Path of the note, such as `"notes/topic.md"`; case-sensitive.
`link_limit`	No	Maximum backlinks, and separately outlinks (default 10).
`similar_limit`	No	Maximum similar notes (default 5); 0 skips them, which suits a vault where stats shows semantic_search_available false.
`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
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv6.1.0Nov 2, 2026

changedInput schema / properties / link_limit / description

Previous value: -"Maximum number of backlinks and outlinks to include\neach (default 10)."New value: +"Maximum backlinks, and separately outlinks (default 10)."

changedInput schema / properties / path / description

Previous value: -"Relative path of the document (e.g. \"notes/topic.md\").\nCase-sensitive."New value: +"Path of the note, such as `\"notes/topic.md\"`; case-sensitive."

changedInput schema / properties / similar_limit / description

Previous value: -"Maximum number of similar notes to include\n(default 5). Pass 0 to skip the similarity lookup — do this\nwhen 'stats' shows semantic_search_available=False (embeddings\nare not configured)."New value: +"Maximum similar notes (default 5); 0 skips them, which suits\na vault where stats shows semantic_search_available false."

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

Changed1 schema field changedv4.0.0Aug 26, 2026

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

Behavior4/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 elsewhere. The description adds behavioral value by disclosing that several result categories are bundled in one call, which implies a batching/cost advantage and that the note body is not returned (only metadata plus link and tag structures). It does not mention result size, pagination beyond the limits, or what happens when a note has no backlinks.

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, zero filler, with the returned categories front-loaded and the routing guidance immediately after. Every clause earns its place.

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 an output schema exists, the description need not explain return shapes, yet it enumerates the categories returned so the agent knows the call's scope. Combined with full schema coverage on all four parameters and annotations covering safety, nothing material is missing for correct invocation.

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 all four parameters carry their own descriptions including defaults and the stale-index fallback. The description adds no parameter-level meaning beyond the schema, so the baseline of 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 names a specific verb ('Return') and resource ('a note's metadata, backlinks, outlinks, similar notes, folder neighbours, indexed tags and applicable conventions'), and explicitly scopes the result as a single aggregated call. An agent can distinguish it from get_backlinks, get_outlinks and get_similar without opening any 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 a clear selection rule: use this 'instead of get_backlinks, get_outlinks and get_similar when you need more than one of them'. That is genuine when-to-use guidance with named alternatives. It stops short of covering other overlapping siblings such as get_conventions or get_toc, and gives no when-not condition beyond the implicit 'more than one' threshold.

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