Markdown Editor MCP Server
This MCP server provides structured, semantic editing of Markdown files by understanding document hierarchy rather than treating files as plain text.
Document Navigation & Discovery:
Parse Markdown files into hierarchical JSON trees showing structure (headings, paragraphs, lists)
Search for text semantically and get element paths (e.g., "Section > paragraph 2")
Read specific elements by their semantic path
View elements with immediate neighbors for context
Search through 15 available tools using natural language queries
Semantic Content Editing:
Replace content of specific blocks without affecting the rest of the document
Insert new elements (headings, paragraphs, lists, code blocks, blockquotes) at precise locations
Move structural blocks and their children to reorganize hierarchy
Delete specific elements by semantic path
Undo last N operations to revert changes
Metadata Management:
Update or add YAML Frontmatter for tools like Obsidian and Jekyll
File System Operations:
List, create, and delete files and directories
Key Advantages: Works with semantic paths instead of line numbers, enables precise edits without rewriting entire files, and is fully MCP 2025 compliant with Tool Search, Examples, Output Schemas, and Dynamic Capabilities.
Supports YAML frontmatter management for Jekyll documents, enabling updates to metadata fields used by Jekyll static site generator.
Provides structured, semantic editing tools for Markdown files, including document structure navigation, content search and replacement, element manipulation (insert, delete, move), YAML frontmatter management, and undo functionality.
Supports YAML frontmatter management for Obsidian notes, allowing manipulation of metadata like tags, dates, and properties used by Obsidian.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Markdown Editor MCP Serversearch for 'deadlines' in my project notes and show me the structure around it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Markdown Editor MCP Server
MCP server providing tools for structured, semantic editing of Markdown files. Unlike standard text editors, this server understands the logical structure of your documents.
Fully compliant with MCP 2025 Standard - includes Tool Search, Examples, Output Schemas, and Dynamic Capabilities.
Installation
From PyPI (recommended)
pip install markdown-editor-mcp-serverFrom source
git clone https://github.com/KazKozDev/markdown-editor-mcp-server.git
cd markdown-editor-mcp-server
pip install -e .Claude Desktop Configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"markdown-editor": {
"command": "markdown-editor-mcp-server"
}
}
}Available Tools
Discovery & Scaling
Why LLMs need this: With 15 tools available, finding the right one can be challenging. This meta-tool helps discover which tool to use for a specific task.
What it does: Searches through all available tools and returns the most relevant ones based on your query.
Parameters:
query(required): Description of what you want to do
Example:
{"query": "replace text"}Semantic Editing
Why LLMs need this: Large Markdown files are hard to navigate. This tool converts the file into a structural tree, allowing the LLM to understand the hierarchy of headings, paragraphs, and lists.
What it does: Parses the Markdown file and returns a JSON tree of all elements with their semantic paths.
Parameters:
file_path(required): Path to the .md filedepth: Max depth for the tree (default: 2)
Example:
{"file_path": "docs/report.md", "depth": 3}Why LLMs need this: Instead of scrolling through an entire file, the LLM can search for specific keywords and get exact semantic paths (e.g., Project > Deadlines > paragraph 2).
What it does: Searches the document for text and returns paths to the containing elements.
Parameters:
file_path(required): Path to the filequery(required): Text to search for
Example:
{"file_path": "todo.md", "query": "urgent"}Why LLMs need this: Before editing an element, you often need to see its full content. This tool fetches the complete content of a specific block.
What it does: Returns the full content of an element identified by its path.
Parameters:
file_path(required): Path to the filepath(required): Semantic path to the element
Example:
{"file_path": "notes.md", "path": "Features > list 1"}Why LLMs need this: Overwriting entire files is risky and token-expensive. This tool allows the LLM to replace the content of a specific semantic block without affecting the rest of the document.
What it does: Replaces text in a specific element identified by its path.
Parameters:
file_path(required): Path to the filepath(required): Semantic path (e.g., "Intro > paragraph 1")new_content(required): New text for the block
Example:
{"file_path": "readme.md", "path": "Installation > paragraph 1", "new_content": "Just run pip install."}Why LLMs need this: Adding new paragraphs, headings, or lists requires understanding document structure. This tool inserts new elements at the right location.
What it does: Inserts a new block (heading, paragraph, list, code block, or blockquote) before or after an existing element.
Parameters:
file_path(required): Path to the filepath(required): Reference element pathelement_type(required): Type (heading, paragraph, list, code_block, blockquote)content(required): Content of the new elementwhere: "before" or "after" (default: "after")heading_level: Level for headings (default: 1)
Example:
{"file_path": "doc.md", "path": "Introduction", "element_type": "paragraph", "content": "New paragraph here."}Why LLMs need this: Removing specific blocks without affecting surrounding content requires precision. This tool deletes elements by their semantic path.
What it does: Removes a block from the document.
Parameters:
file_path(required): Path to the filepath(required): Semantic path to the element to delete
Example:
{"file_path": "draft.md", "path": "Old Section"}Why LLMs need this: Reorganizing a document is complex. This tool lets the LLM move entire sections (including all nested sub-elements) to a new location with a single command.
What it does: Moves a block of text from source path to target path.
Parameters:
file_path(required): Path to the filesource_path(required): Path of element to movetarget_path(required): Reference path for new locationwhere: "before" or "after" the target (default: "after")
Example:
{"file_path": "draft.md", "source_path": "Contacts", "target_path": "Conclusion"}Why LLMs need this: When editing a single block, LLMs might lose the narrative flow. This tool provides the target element along with its immediate neighbors (before and after).
What it does: Fetches an element and snippets of surrounding blocks.
Parameters:
file_path(required): Path to the filepath(required): Path to the target element
Example:
{"file_path": "article.md", "path": "Body > paragraph 5"}Why LLMs need this: Many Markdown tools (Obsidian, Jekyll) use YAML metadata at the top. This tool allows the LLM to manage tags, dates, and properties without messing with the body text.
What it does: Updates or adds YAML Frontmatter to the document.
Parameters:
file_path(required): Path to the filemetadata(required): Dictionary of metadata items
Example:
{"file_path": "post.md", "metadata": {"status": "published", "tags": ["mcp", "ai"]}}Why LLMs need this: Mistakes happen. This tool allows reverting recent operations without manual file restoration.
What it does: Reverts the last N operations on the document.
Parameters:
file_path(required): Path to the filecount: Number of operations to undo (default: 1)
Example:
{"file_path": "document.md", "count": 2}File Operations
What it does: Lists files and folders in a directory, helping the LLM explore the file structure.
Parameters:
path: Directory path (default: ".")
What it does: Creates a new file with optional initial content.
Parameters:
path(required): Path to the new filecontent: Initial content (default: "")
Example:
{"path": "./notes/todo.md", "content": "# TODO\n\n- Task 1"}What it does: Creates a new directory.
Parameters:
path(required): Path to the new directory
Example:
{"path": "./docs/archive"}What it does: Deletes a file or directory.
Development
# Install for development
pip install -e .
# Run tests
pytest tests/MCP 2025 Standard Features
This server implements all 2025 MCP improvements:
Tool Search Tool - Efficiently find the right tool among many options
Tool Use Examples - Input parameter examples help LLMs use tools correctly
Output Schemas - Structured output definitions for better client integration
Dynamic Capabilities - Support for
tools/list_changednotifications
If you like this project, please give it a star ⭐
Available Tools
15 toolscreate_directoryCreate DirectoryD
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| path | No | |
| success | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_fileCreate FileD
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| path | No | |
| size | No | |
| success | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_elementDelete BlockC
Removes a block from the document.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| success | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Removes') but lacks details on permissions needed, whether the deletion is permanent or reversible, error handling, or effects on the document structure. This is insufficient for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words, making it highly concise and front-loaded. It efficiently conveys the core action without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, no annotations, and an output schema (which might cover return values), the description is incomplete. It doesn't address safety, permissions, or error scenarios, leaving significant gaps for an AI agent to understand proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate but fails to do so. It doesn't explain what 'file_path' and 'path' parameters mean, their formats, or how they interact. This leaves key input semantics undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Removes') and the resource ('a block from the document'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'delete_item' or 'move_element', which might also remove content, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'delete_item' or 'move_element', nor does it mention prerequisites like file existence or permissions. It's a basic statement without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_itemDelete File/FolderD
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| path | No | |
| success | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_contextGet Element ContextB
Returns the target element along with its immediate neighbors (before and after).
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| path | Yes | Path to the element (e.g., 'Intro > paragraph 1') |
Output Schema
| Name | Required | Description |
|---|---|---|
| after | No | Element after target |
| before | No | Element before target |
| target | No | The target element |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the return content without disclosing behavioral traits like error handling, performance, or side effects. It doesn't mention if it's read-only, safe, or has any limitations beyond the basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core functionality with zero waste. Every word contributes directly to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values) and moderate complexity, the description is minimally adequate but lacks depth. It covers the basic operation but misses behavioral context and usage guidelines, leaving gaps in completeness for a tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'path' has a description), and the description adds no parameter-specific details beyond what the schema provides. It implies parameters are used to locate the element but doesn't explain their roles or interactions, resulting in a baseline score due to moderate schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Returns') and resource ('target element along with its immediate neighbors'), specifying the scope ('before and after'). It distinguishes from siblings like 'read_element' (which likely returns only the element) and 'get_document_structure' (which likely returns broader structure), though not explicitly named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'read_element' or 'get_document_structure' is provided. The description implies usage for contextual analysis but lacks prerequisites, exclusions, or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_document_structureGet Document StructureA
Parses the Markdown file and returns a tree of headings and elements. Use this first to navigate.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .md file | |
| depth | No | Maximum depth of headings to return |
Output Schema
| Name | Required | Description |
|---|---|---|
| structure | No | Tree of document elements |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the tool's behavior as parsing and returning a tree, which implies a read-only operation without side effects, but lacks details on error handling, performance, or output format specifics. It adds some context with the navigation advice but is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core functionality in the first sentence and adds a concise usage tip in the second. Both sentences earn their place by providing essential information without redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (parsing Markdown structure), no annotations, and the presence of an output schema (which handles return values), the description is reasonably complete. It covers purpose and usage but could improve by addressing behavioral aspects like error cases or limitations, though the output schema mitigates some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters (file_path and depth). The description adds no additional parameter semantics beyond what the schema provides, such as explaining how depth affects the tree structure or file_path validation, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('parses the Markdown file') and the resource/result ('returns a tree of headings and elements'), distinguishing it from siblings like read_element or search_text by focusing on structural analysis rather than content reading or searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance to 'use this first to navigate,' indicating a primary use case for initial exploration of document structure. However, it does not specify when not to use it or name alternatives among siblings, such as read_element for content reading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
insert_elementInsert New ElementB
Inserts a new block (heading, paragraph, etc.) relative to an existing one.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| path | Yes | Reference path | |
| element_type | Yes | ||
| content | Yes | ||
| where | No | after | |
| heading_level | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| success | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an insertion operation but doesn't mention whether this modifies files in-place, requires write permissions, has side effects, or what happens on failure. For a tool that modifies documents, this lack of behavioral context is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action. Every word earns its place by specifying what's inserted (new block), what types are possible, and the relative positioning. There's no wasted verbiage or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (though not shown), the description doesn't need to explain return values. However, for a tool with 6 parameters, low schema coverage (17%), and no annotations, the description should provide more context about the insertion behavior, error conditions, and relationship to sibling tools. It's minimally adequate but leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, with only one parameter ('path') having a description. The description adds minimal value by mentioning 'relative to an existing one' which hints at the 'path' and 'where' parameters, but doesn't explain the purpose of 'file_path', 'element_type', 'content', or 'heading_level'. The baseline is 3 since the description provides some context but doesn't compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'inserts' and resource 'new block' with examples of block types. It specifies the action is relative to an existing element, which distinguishes it from tools like 'create_file' or 'replace_content'. However, it doesn't explicitly differentiate from similar tools like 'move_element' or 'update_metadata'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'create_file', 'replace_content', 'move_element', or 'update_metadata'. It mentions the action is 'relative to an existing one' but doesn't clarify when this specific insertion approach is preferred over other content modification methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_directoryList DirectoryB
Lists files and folders in the workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . |
Output Schema
| Name | Required | Description |
|---|---|---|
| items | No | List of directory entries |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't describe traits like whether it's read-only, pagination behavior, error handling for invalid paths, or output format details. This leaves significant gaps for a tool that interacts with filesystem-like resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to scan and understand quickly without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional parameter) and the presence of an output schema, the description is minimally adequate. However, with no annotations and incomplete behavioral context, it doesn't fully compensate for the lack of structured metadata, leaving gaps in understanding how the tool behaves in practice.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds no parameter information beyond what the schema already shows (a 'path' parameter). The schema provides examples like '.' and '/path/to/directory', while the description doesn't elaborate on semantics such as relative vs. absolute paths or default behavior. Baseline 3 is appropriate as the schema does the minimal documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Lists') and resource ('files and folders in the workspace'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_document_structure' or 'search_text', which might also involve listing content, so it misses full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_text' for filtered results or 'get_document_structure' for hierarchical views. It lacks explicit when/when-not instructions or named alternatives, leaving usage context implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
move_elementMove Structural BlockB
Moves an element (and its children) to a new location in the document.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| source_path | Yes | ||
| target_path | Yes | ||
| where | No | after |
Output Schema
| Name | Required | Description |
|---|---|---|
| success | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions moving 'an element (and its children)', implying hierarchical effects, but fails to detail critical traits like whether the operation is destructive (e.g., overwrites target), requires specific permissions, or has side effects like updating references. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and resource. Every word earns its place by specifying the move operation, the element scope (including children), and the destination context, with no redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation with 4 parameters) and the presence of an output schema (which alleviates need to explain return values), the description is minimally adequate. However, with no annotations and low schema coverage, it lacks completeness in behavioral and parameter details, making it just sufficient for basic understanding but insufficient for robust agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no specific meaning beyond the input schema, which has 0% description coverage. It implies parameters for source, target, and file context but doesn't explain semantics like path formats or the 'where' enum's effect. With low schema coverage, the description fails to compensate, resulting in a baseline score due to the lack of parameter details in either source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Moves'), the resource ('an element (and its children)'), and the context ('to a new location in the document'). It distinguishes from siblings like 'delete_element' or 'insert_element' by specifying relocation rather than removal or addition. However, it doesn't explicitly differentiate from 'replace_content' which might involve movement, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'insert_element' for adding new content or 'delete_element' for removal. It lacks context on prerequisites, such as needing an existing element to move, or exclusions, like not being suitable for non-structural changes. This leaves the agent with minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_elementRead Specific ElementC
Fetches the full content of a specific block by its path.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | No | Element content |
| element | No | The requested element |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'fetches' content, implying a read operation, but doesn't cover critical aspects like error handling (e.g., if the path is invalid), performance (e.g., rate limits), or output format (though an output schema exists). This leaves gaps in understanding how the tool behaves beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('fetches') and resource. There is no wasted wording, and it directly communicates the tool's function without unnecessary elaboration, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 required parameters) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and 0% schema coverage, it lacks details on error cases, permissions, or behavioral nuances. It meets a basic threshold but doesn't provide a complete picture for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description mentions 'by its path' but doesn't explain what 'file_path' and 'path' represent or how they differ (e.g., file location vs. block hierarchy). It adds minimal semantic value beyond the parameter names, failing to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('fetches') and resource ('full content of a specific block'), making the purpose understandable. It distinguishes from siblings like 'get_document_structure' (which likely lists elements) or 'search_text' (which searches content). However, it doesn't explicitly differentiate from 'get_context' or other read-like siblings, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the file to exist), exclusions (e.g., not for metadata), or comparisons to siblings like 'get_document_structure' for overviews or 'search_text' for content queries. Usage is implied by the name but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
replace_contentReplace Block ContentB
Overwrites the content of a specific block. Maintains document structure.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| path | Yes | ||
| new_content | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| success | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states 'Overwrites' (implying mutation) and 'Maintains document structure', but lacks details on permissions, reversibility (e.g., via 'undo'), error handling, or side effects. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that are front-loaded and waste no words. Every phrase ('Overwrites the content', 'specific block', 'Maintains document structure') adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a mutation tool with 3 parameters, 0% schema coverage, no annotations, but an output schema (which reduces need to explain returns), the description is incomplete. It covers the basic purpose but lacks usage guidelines, behavioral details, and parameter semantics, making it minimally viable but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it adds no parameter-specific information beyond what the schema's examples imply. The description doesn't explain 'path' semantics or 'new_content' constraints, leaving parameters largely undocumented. Baseline 3 is applied due to the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Overwrites') and target ('content of a specific block'), and distinguishes it from siblings like 'update_metadata' or 'insert_element' by focusing on replacement rather than creation or modification of metadata. However, it doesn't explicitly differentiate from 'delete_element' or 'read_element' in terms of scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'update_metadata', 'insert_element', or 'delete_element'. It mentions maintaining document structure, but doesn't specify prerequisites, exclusions, or contextual cues for selection among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_textSearch Text in DocumentB
Performs a semantic search for text strings and returns their structural paths.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| query | Yes | String to search for |
Output Schema
| Name | Required | Description |
|---|---|---|
| results | No | List of matching elements with their paths |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'semantic search' and 'returns structural paths', but lacks details on permissions, rate limits, error handling, or what 'structural paths' entail (e.g., format, depth). This is a significant gap for a search tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. Every word earns its place, with no redundant or vague phrasing. It's appropriately sized for a tool with two parameters and an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (semantic search), no annotations, and an output schema (which handles return values), the description is minimally adequate. However, it lacks context on behavioral traits and parameter nuances, leaving gaps in understanding how to use it effectively beyond basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'query' has a description), and the description adds no parameter-specific information beyond what's in the schema. It doesn't explain 'file_path' semantics (e.g., supported formats, relative vs. absolute paths) or clarify 'semantic search' for the 'query' parameter. Baseline 3 is appropriate as the schema partially documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('performs a semantic search for text strings') and the resource ('in document'), distinguishing it from siblings like 'search_tools' (which appears to be a meta-tool) and 'get_document_structure' (which retrieves structure without searching). The verb 'search' is specific and the scope is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'search_text' over 'search_tools' or 'get_context', nor does it specify prerequisites like file existence or format compatibility. Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_toolsSearch ToolsC
Scalability feature: find the right tool for your complex task among all available tools.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Description of the operation you want to perform |
Output Schema
| Name | Required | Description |
|---|---|---|
| tools | No | List of relevant tool names |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'scalability feature' but doesn't explain what this entails—such as performance characteristics, rate limits, or authentication needs. The description lacks details on how the search works, what the output includes, or any constraints, making it insufficient for a tool with behavioral implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and efficient, with no wasted words. It directly states the tool's purpose without unnecessary elaboration. However, it could be slightly more structured by explicitly mentioning the scope (e.g., 'among sibling tools') to improve clarity without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is an output schema (which reduces the need to describe return values) and high schema coverage, the description is minimally adequate. However, for a search tool with no annotations and behavioral aspects like scalability, it should provide more context on how results are ranked or what 'scalability feature' means. The description is incomplete in addressing these nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'query' parameter well-documented as a string describing the operation. The description adds no additional meaning beyond the schema, such as clarifying search syntax or result relevance. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'find the right tool for your complex task among all available tools,' which specifies the verb 'find' and the resource 'tool.' It distinguishes itself from siblings like 'search_text' by focusing on tool discovery rather than content searching. However, it doesn't explicitly mention that it searches among the sibling tools listed, which could make it slightly less specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't specify scenarios where searching for tools is preferable over directly using known tools like 'list_directory' or 'search_text,' nor does it mention prerequisites or exclusions. This lack of context leaves the agent without clear usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
undoUndo Last ChangesB
Reverts the last N operations on the document.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| count | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| success | No | |
| reverted_count | No | Number of operations reverted |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'reverts' implies a mutation that changes document state, it doesn't specify whether this is destructive (e.g., irreversible), has side effects (e.g., affects other tools), requires specific permissions, or details error conditions (e.g., what happens if N exceeds available operations). For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('reverts') and key parameters ('last N operations'). There is no wasted wording, making it easy to parse quickly while conveying essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation with 2 parameters, no annotations, but with an output schema), the description is minimally adequate. The output schema likely covers return values, reducing the need for that in the description. However, for a tool that modifies document state, more details on behavior, constraints, and usage context would improve completeness, especially with no annotations to fill gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds some meaning by explaining that 'count' refers to 'last N operations,' which clarifies the parameter's purpose beyond the schema's basic type and examples. However, with 0% schema description coverage, it doesn't fully compensate for the lack of details on 'file_path' (e.g., format requirements or path validity) or constraints on 'count' (e.g., maximum value). The baseline is 3 due to partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('reverts') and resource ('operations on the document'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'replace_content' or 'update_metadata' that might also modify documents, leaving some ambiguity about when to use undo versus other modification tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., requires an open document), exclusions (e.g., cannot undo after saving), or compare to siblings like 'replace_content' for specific edits. This lack of context makes it harder for an agent to choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_metadataUpdate YAML MetadataB
Modifies the document's Frontmatter.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| metadata | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| success | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Modifies' implies a mutation operation, but it doesn't address critical aspects like whether this overwrites or merges metadata, what permissions are required, if changes are reversible, or what happens on errors. For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a simple tool and front-loads the core purpose immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with 2 parameters, nested objects, no annotations, but with an output schema, the description is minimally adequate. The output schema reduces the need to describe return values, but the description should do more to explain behavioral aspects and parameter usage for a tool that modifies documents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't explain either parameter beyond what the schema shows through examples. With 0% schema description coverage, the description adds no semantic value about 'file_path' or 'metadata' parameters. However, since there are only 2 parameters and the schema provides clear examples, this meets the baseline for minimal viability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Modifies') and target ('document's Frontmatter'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'replace_content' or 'insert_element' that might also modify document content, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'replace_content' or 'insert_element' for document modifications. It mentions the target ('Frontmatter') but doesn't specify prerequisites, exclusions, or contextual usage patterns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Most tools have distinct purposes, but there is notable overlap between delete_element and delete_item, which could cause confusion as their descriptions are unclear or missing. Additionally, search_tools is ambiguous and doesn't fit cleanly with the document editing focus, potentially leading to misselection.
The naming follows a consistent verb_noun pattern (e.g., create_directory, insert_element, move_element) with only minor deviations like search_tools and undo, which are less structured but still readable. Overall, the conventions are predictable and aid in tool identification.
With 15 tools, the count is well-scoped for a Markdown editor server, covering file management, document structure manipulation, content editing, and search functionalities. Each tool appears to serve a specific role without feeling excessive or insufficient for the domain.
The tool set provides comprehensive coverage for Markdown editing, including CRUD operations for files and elements, navigation, and undo functionality. A minor gap exists in lacking a dedicated tool for creating or modifying specific Markdown elements like lists or code blocks, but agents can work around this using insert_element and replace_content.
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Create, edit, review, and explicitly publish Live or Snapshot Markdown Documents in mdedit.ai.
MCP-native collaborative markdown editor with real-time AI document editing
High-fidelity PDF to structured Markdown conversion and document field extraction.
Appeared in Searches
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/KazKozDev/markdown-editor-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server