markdown-vault-mcp

Edit Note

edit

Replace targeted text or line ranges in Markdown notes using exact, scoped, or line-range matching to apply precise updates safely.

Instructions

Make a targeted text replacement in an existing .md note (not supported for attachments).

Three edit modes:

Exact match (old_text only): pass a portion of the file as old_text — must appear exactly once. Frontmatter can be edited.
Line-range (line_start + line_end, no old_text): replace the specified lines with new_text. Lines are 1-based (matching 'read' output). Recommended: pass if_match for safety.
Scoped match (old_text + line_start/line_end): search for old_text within the line range only — useful when old_text appears multiple times in the file.

When exact match fails, a normalized comparison is attempted (Unicode NFC, dash/quote normalization, whitespace collapsing). If a unique normalized match is found, it is used and match_type='normalized' is returned.

Always call 'read' first to get the current text and line numbers. The index refresh is queued; no reindex is needed.

Input Schema

TableJSON Schema

Name	Required	Description
`path`	Yes	Relative path to the document.
`if_match`	No	Optional etag obtained from a previous 'read' call. When provided, the edit only proceeds if the file has not been modified since that read (optimistic concurrency).
`line_end`	No	Last line to replace (1-based, inclusive). Must be provided together with line_start.
`new_text`	No	Replacement text. May be longer or shorter.
`old_text`	No	Text to replace. Must appear exactly once in the document or line range. Get this via 'read'. Optional when using line-range mode.
`line_start`	No	First line to replace (1-based, inclusive). Must be provided together with line_end.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv4.0.0Aug 26, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations are minimal (only hints about read-only, idempotency, destructiveness), so the description carries the full burden. It fully discloses behavior: three edit modes, normalization fallback with match_type='normalized', queued index refresh, and the need for a prior 'read'. This exceeds what annotations provide.

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?

Well-structured with a clear opening line, bullet-pointed modes, and a closing operational note. Every sentence earns its place; no redundancy. The most critical instruction (call read first) is placed near the end but is highlighted separately, and the overall length is justified by the tool's complexity.

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 tool's complexity (3 modes, normalization, concurrency), the description covers all essential context: how to invoke each mode, the normalization fallback, the index refresh behavior, and the prerequisite of reading first. An output schema exists, so not describing return values is acceptable. Nothing critical is missing.

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 each parameter is individually documented. The description adds value by explaining the relationships between parameters (e.g., line-range mode requires line_start+line_end and omits old_text; scoped match combines old_text with a range). This contextual semantics goes beyond the schema's per-field descriptions.

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 states a specific action ('targeted text replacement') on a specific resource ('existing .md note') and explicitly excludes attachments, clearly distinguishing it from write/append/delete/rename siblings. The three modes are detailed, leaving no ambiguity about what the tool does.

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?

Provides explicit guidance on when to use each mode, instructs to always call 'read' first, and recommends passing if_match for safety. It doesn't explicitly contrast with sibling tools like 'write' or 'append', but the purpose is distinct enough that an agent can infer when to use it.

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