Skip to main content
Glama
quantalogic

SafeMarkdownEditor MCP Server

by quantalogic
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

SafeMarkdownEditor MCP Server

A Model Context Protocol (MCP) server that provides powerful Markdown document editing capabilities with thread-safe operations, atomic transactions, and comprehensive validation.

📦 Available on PyPI: quantalogic-markdown-mcp

🚀 Quick Start: Install with uv add quantalogic-markdown-mcp or pip install quantalogic-markdown-mcp

Current version: 0.1.2

Features

✨ Comprehensive Markdown Editing

  • Insert, update, delete, and move sections

  • Thread-safe operations with atomic transactions

  • Immutable section references that remain stable across edits

  • Comprehensive validation with configurable strictness levels

🔧 MCP Tools Available

File Operations:

  • load_document - Load a Markdown document from a file path (supports absolute, relative, and ~ expansion)

  • save_document - Save the current document to a file path

  • get_file_info - Get information about the currently loaded file

  • test_path_resolution - Test and verify path resolution for different path formats

Document Editing:

  • insert_section - Insert new sections at specified positions

  • delete_section - Remove sections by ID or heading

  • update_section - Modify section content while preserving structure

  • move_section - Reorder sections within the document

  • get_section - Retrieve individual section content and metadata

  • list_sections - Get an overview of all document sections

  • get_document - Export the complete Markdown document

  • undo - Rollback the last operation

📊 MCP Resources

  • document://current - Real-time access to the current document

  • document://history - Transaction history for undo/redo operations

  • document://metadata - Document metadata (title, author, timestamps)

🎯 MCP Prompts

  • summarize_section - Generate section summaries

  • rewrite_section - Improve section clarity and conciseness

  • generate_outline - Create document outlines

Related MCP server: Markdown Editor MCP Server

Installation

Prerequisites

  • Python 3.11 or higher

  • uv (recommended) or pip

Quick Install from PyPI (Recommended)

The package is available on PyPI! Install the latest version (0.1.2) directly:

# Install with uv (recommended)
uv add quantalogic-markdown-mcp@0.1.2

# Or install with pip
pip install quantalogic-markdown-mcp==0.1.2

Run Directly with uvx (No Installation Required)

You can run the MCP server directly without installing it locally:

# Run directly with uvx
uvx --from quantalogic-markdown-mcp python -m quantalogic_markdown_mcp.mcp_server

Development Installation

For development or to contribute to the project:

# Clone the repository
git clone https://github.com/raphaelmansuy/quantalogic-markdown-edit-mcp.git
cd quantalogic-markdown-edit-mcp

# Install with development dependencies
uv sync --group dev

# Install in development mode
uv pip install -e .

Quick Start

Running the Server

Method 1: Direct Execution (PyPI Installation)

If you installed from PyPI:

# Run the MCP server directly (ensure version 0.1.2 is installed)
python -m quantalogic_markdown_mcp.mcp_server

# Or with uvx (no installation required)
uvx --from quantalogic-markdown-mcp python -m quantalogic_markdown_mcp.mcp_server

Method 2: Development Installation

If you cloned the repository:

# Using uv
uv run python -m quantalogic_markdown_mcp.mcp_server

# Or with regular Python
python -m quantalogic_markdown_mcp.mcp_server

Method 3: Using the Development Script

For development from source:

# Run the development server (dev mode)
python dev-scripts/run_mcp_server.py

Connecting to Claude Desktop

To use this MCP server with Claude Desktop, add the following configuration to your claude_desktop_config.json:

Option 1: Using PyPI Installation (Recommended)

macOS/Linux:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "python",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "python.exe",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Option 2: Using uvx (No Installation Required)

macOS/Linux:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "uvx",
      "args": [
        "--from",
        "quantalogic-markdown-mcp",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "uvx.exe",
      "args": [
        "--from",
        "quantalogic-markdown-mcp",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Option 3: Development Installation

For development from source:

macOS/Linux:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/quantalogic-markdown-edit-mcp",
        "run",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "uv.exe",
      "args": [
        "--directory",
        "C:\\ABSOLUTE\\PATH\\TO\\quantalogic-markdown-edit-mcp",
        "run",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Configuration file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

After adding the configuration, restart Claude Desktop.

Connecting to VSCode

To use this MCP server with VSCode and GitHub Copilot, you have several configuration options depending on your needs.

Prerequisites:

  • VSCode 1.102 or later

  • GitHub Copilot extension installed and configured

  • MCP support enabled in your organization (if applicable)

Workspace Configuration (Recommended for Projects)

Create a .vscode/mcp.json file in your workspace root to share the configuration with your team:

Option 1: Development Installation (Recommended)

For this project, use the development setup since you're working with the source code:

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run",
        "python",
        "-c",
        "import sys; sys.path.insert(0, 'src'); from quantalogic_markdown_mcp.mcp_server import mcp; mcp.run()"
      ],
      "cwd": "${workspaceFolder}"
    }
  }
}

Option 2: Alternative Development Approach

Using environment variables for Python path:

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run",
        "--",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

Option 3: Using PyPI Installation (If Installed Globally)

Only use this if you have installed the package globally:

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "python3",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

For Windows (adjust command names):

{
  "servers": {
    "markdown-editor": {
      "type": "stdio", 
      "command": "python.exe",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

User Configuration (Global Settings)

For system-wide access across all workspaces:

  1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)

  2. Run MCP: Open User Configuration

  3. Add the server configuration:

Option 1: Using PyPI Installation

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "python",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Option 2: Using uvx

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "quantalogic-markdown-mcp",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Option 3: Development Installation

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/quantalogic-markdown-edit-mcp",
        "run",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Development Container Support

For containerized development environments, add to your devcontainer.json:

{
  "image": "mcr.microsoft.com/devcontainers/python:latest",
  "customizations": {
    "vscode": {
      "mcp": {
        "servers": {
          "markdown-editor": {
            "type": "stdio",
            "command": "uv",
            "args": [
              "--directory", 
              "${containerWorkspaceFolder}",
              "run",
              "python",
              "-m", 
              "quantalogic_markdown_mcp.mcp_server"
            ]
          }
        }
      }
    }
  }
}

Alternative Installation Methods

Command Line Installation:

code --add-mcp '{"name":"markdown-editor","command":"uv","args":["--directory","/ABSOLUTE/PATH/TO/quantalogic-markdown-edit-mcp","run","python","-m","quantalogic_markdown_mcp.mcp_server"]}'

URL Installation: You can create installation links using the VSCode URL handler format:

vscode:mcp/install?%7B%22name%22%3A%22markdown-editor%22%2C%22command%22%3A%22uv%22%2C%22args%22%3A%5B%22--directory%22%2C%22%2FABSOLUTE%2FPATH%2FTO%2Fquantalogic-markdown-edit-mcp%22%2C%22run%22%2C%22python%22%2C%22-m%22%2C%22quantalogic_markdown_mcp.mcp_server%22%5D%7D

Using the MCP Server in VSCode

Once configured:

  1. Open the Chat view (Ctrl+Cmd+I / Ctrl+Alt+I)

  2. Select Agent mode from the dropdown

  3. Click the Tools button to see available MCP tools

  4. Enable the markdown-editor tools you want to use

  5. Start chatting with commands like:

    • "Load the README.md file and show me all sections"

    • "Create a new section called 'Installation' with setup instructions"

    • "Move the 'Features' section to be the first section"

Managing MCP Servers:

  • View installed servers: MCP: List Servers

  • Manage servers: Go to Extensions view (Ctrl+Shift+X) → MCP SERVERS section

  • View server logs: Right-click server → Show Output

  • Start/Stop servers: Right-click server → Start/Stop/Restart

Development and Debugging:

For development, you can enable watch mode and debugging in your .vscode/mcp.json:

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run", 
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ],
      "dev": {
        "watch": "src/**/*.py",
        "debug": { "type": "python" }
      }
    }
  }
}

Working with Files

The MCP server supports loading and saving Markdown documents from various file path formats:

Supported Path Formats

  • Absolute paths: /Users/username/documents/file.md

  • Relative paths: ./documents/file.md or documents/file.md

  • Home directory expansion: ~/Documents/file.md

  • Environment variables: $HOME/documents/file.md

File Operations Examples

"Load the document from ~/Documents/my-notes.md"
"Load the file at ./project-docs/README.md"
"Save this document to /Users/me/Desktop/backup.md"
"Get information about the current file"
"Test if the path ~/Documents/draft.md resolves correctly"

Usage Examples

Basic Document Operations

Once connected to Claude Desktop (or another MCP client), you can use natural language commands:

"Load the document from ~/Documents/my-project.md"
"Create a new section called 'Getting Started' with some basic instructions"
"Move the 'Installation' section to be the second section"
"Update the 'Features' section to include the new functionality"
"Delete the 'Deprecated' section"
"Save the document to ./backups/project-backup.md"
"Show me all the sections in this document"
"Get the current document as Markdown"

Working with Different Path Types

"Load /Users/me/Documents/important-notes.md"
"Load the file at ./project-docs/specification.md"
"Load ~/Desktop/meeting-notes.md"
"Test if the path $HOME/Documents/draft.md exists"
"Save to /tmp/quick-backup.md with backup enabled"

Programmatic Usage

You can also use the server programmatically with FastMCP clients:

import asyncio
from fastmcp import Client

async def demo():
    # Connect to the server (adjust command based on your installation)
    
    # Option 1: If installed from PyPI
    async with Client("python -m quantalogic_markdown_mcp.mcp_server") as client:
        # ... rest of the code remains the same
        
    # Option 2: If using development installation
    # async with Client("src/quantalogic_markdown_mcp/mcp_server.py") as client:
    
        # List available tools
        tools = await client.list_tools()
        print(f"Available tools: {[tool.name for tool in tools]}")
        
        # Load a document from file
        result = await client.call_tool("load_document", {
            "file_path": "~/Documents/my-notes.md",
            "validation_level": "NORMAL"
        })
        print(f"Load result: {result.content}")
        
        # Get file information
        file_info = await client.call_tool("get_file_info", {})
        print(f"File info: {file_info.content}")
        
        # Test path resolution
        path_test = await client.call_tool("test_path_resolution", {
            "path": "~/Documents/test.md"
        })
        print(f"Path resolution: {path_test.content}")
        
        # Insert a new section
        result = await client.call_tool("insert_section", {
            "heading": "Introduction",
            "content": "Welcome to our documentation!",
            "position": 0
        })
        print(f"Insert result: {result.content}")
        
        # List all sections
        sections = await client.call_tool("list_sections", {})
        print(f"Document sections: {sections.content}")
        
        # Save the modified document
        save_result = await client.call_tool("save_document", {
            "file_path": "./modified-notes.md",
            "backup": True
        })
        print(f"Save result: {save_result.content}")

# Run the demo
asyncio.run(demo())

Tool Reference

File Operation Tools

load_document(file_path: str, validation_level: str = "NORMAL")

Load a Markdown document from a file path with support for various path formats.

Parameters:

  • file_path: Path to the Markdown file (supports absolute, relative, ~, and $ENV expansion)

  • validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"

Returns: Success status with file information and document statistics

Examples:

  • load_document("/Users/me/notes.md")

  • load_document("./docs/README.md")

  • load_document("~/Documents/project.md")

save_document(file_path?: str, backup: bool = True)

Save the current document to a file path.

Parameters:

  • file_path: Target path to save to (optional, uses current file if not provided)

  • backup: Whether to create a .bak backup of existing files

Returns: Success status with save location information

get_file_info()

Get detailed information about the currently loaded file.

Returns: File metadata including path, size, permissions, and timestamps

test_path_resolution(path: str)

Test and validate path resolution for different path formats.

Parameters:

  • path: The path to test and resolve

Returns: Detailed path resolution information including expansion details

Document Editing Tools

insert_section(heading: str, content: str, position: int)

Insert a new section at the specified position.

Parameters:

  • heading: The section heading text

  • content: The section content (can include Markdown)

  • position: Where to insert (0 = beginning, or after existing section)

Returns: Success/failure status with section ID if successful

delete_section(section_id?: str, heading?: str)

Delete a section by ID or heading.

Parameters:

  • section_id: Unique section identifier (optional)

  • heading: Section heading text (optional)

Note: Either section_id or heading must be provided.

update_section(section_id: str, content: str)

Update the content of an existing section.

Parameters:

  • section_id: Unique section identifier

  • content: New content for the section

move_section(section_id: str, new_position: int)

Move a section to a new position in the document.

Parameters:

  • section_id: Unique section identifier

  • new_position: Target position (0-based)

get_section(section_id: str)

Retrieve detailed information about a specific section.

Returns: Section heading, content, position, level, and ID

list_sections()

Get metadata for all sections in the document.

Returns: Array of section metadata (ID, heading, position, level, path)

get_document()

Export the complete Markdown document.

Returns: Full document as Markdown text

undo()

Undo the last operation performed on the document.

Returns: Success/failure status

Configuration Options

The server supports several configuration options through environment variables:

# Validation level (STRICT, NORMAL, PERMISSIVE)
export MARKDOWN_VALIDATION_LEVEL=NORMAL

# Maximum transaction history size
export MAX_TRANSACTION_HISTORY=100

# Server name
export MCP_SERVER_NAME="SafeMarkdownEditor"

Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Run specific test files
uv run pytest tests/test_mcp_server.py

Code Quality

# Format code
uv run black src tests

# Lint code
uv run ruff check src tests

# Type checking
uv run mypy src

Development Server

For development, you can run the server with additional debugging:

# In dev-scripts/run_mcp_server.py
from quantalogic_markdown_mcp.mcp_server import server

if __name__ == "__main__":
    # Initialize with debug document
    server.initialize_document(
        markdown_text="""# Sample Document

## Introduction
This is a sample document for testing.

## Features  
- Feature 1
- Feature 2

## Conclusion
Thank you for reading!
""",
        validation_level=ValidationLevel.NORMAL
    )
    
    print("Starting SafeMarkdownEditor MCP Server...")
    print("Debug mode enabled with sample document")
    server.run()

Troubleshooting

Common Issues

Server not appearing in Claude Desktop:

  1. Check that the path in claude_desktop_config.json is absolute

  2. Verify that uv is in your PATH (which uv on macOS/Linux, where uv on Windows)

  3. Restart Claude Desktop after configuration changes

  4. Check Claude Desktop logs for error messages

Server not appearing in VSCode:

  1. Ensure VSCode 1.102 or later is installed

  2. Verify GitHub Copilot extension is installed and active

  3. Check that MCP support is enabled in your organization settings

  4. Confirm .vscode/mcp.json file exists in workspace root (for workspace config)

  5. Use MCP: List Servers command to see if server is registered

  6. Check Extensions view → MCP SERVERS section for server status

  7. Verify uv is in your PATH and accessible from VSCode's integrated terminal

VSCode MCP server not starting:

  1. Check the MCP server output: Right-click server → Show Output

  2. For development setup: Ensure you're using the correct configuration:

    {
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run",
        "--",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

  3. Verify the command path and arguments in your configuration

  4. Test the command manually in a terminal from the correct working directory:

    cd /path/to/quantalogic-markdown-edit-mcp
uv run python -c "import sys; sys.path.insert(0, 'src'); from quantalogic_markdown_mcp.mcp_server import mcp; print('MCP server ready')"

  5. Ensure all required dependencies are installed: uv sync

  6. Check file permissions on the server executable

  7. For dev containers, verify the container has access to required tools

VSCode agent mode not showing MCP tools:

  1. Confirm you're in Agent mode (not Ask mode) in the Chat view

  2. Click the Tools button to enable/disable specific MCP tools

  3. Check if you have more than 128 tools enabled (VSCode limit)

  4. Verify the MCP server is running (green indicator in Extensions view)

  5. Try restarting the MCP server: Right-click → Restart

Tool execution errors:

  1. Ensure the document is initialized (the server auto-initializes if needed)

  2. Check section IDs are valid using list_sections first

  3. Verify that section references haven't changed after edits

Performance issues:

  1. Large documents may take time to process

  2. Consider using section-level operations instead of full document operations

  3. Monitor transaction history size

Debug Mode

Enable debug logging by setting:

export PYTHONPATH=$PWD/src
export MCP_DEBUG=1
python -m quantalogic_markdown_mcp.mcp_server

Logging

The server uses Python's logging module and writes to stderr to avoid interfering with MCP's stdio transport. To see debug logs:

# Run with debug logging
PYTHONPATH=$PWD/src python -m quantalogic_markdown_mcp.mcp_server 2>debug.log

Architecture

The server is built on several key components:

  • SafeMarkdownEditor: Core thread-safe editing engine with atomic operations

  • MarkdownMCPServer: MCP server wrapper that exposes editing capabilities

  • FastMCP: Modern MCP framework for Python with automatic schema generation

  • Transaction System: Atomic operations with rollback support

  • Validation Engine: Configurable document structure validation

Contributing

Contributions are welcome! Please read our contributing guidelines:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes with tests

  4. Ensure all tests pass and code is formatted

  5. Submit a pull request

Development Setup

# Clone and setup
git clone https://github.com/raphaelmansuy/quantalogic-markdown-edit-mcp.git
cd quantalogic-markdown-edit-mcp

# Install with development dependencies
uv sync --group dev

# Install pre-commit hooks
uv run pre-commit install

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

Need help? Open an issue on GitHub or check the documentation.

Available Tools

10 tools
analyze_documentC
        Analyze document structure and provide insights.
        
        Args:
            document_path: Path to the Markdown file
            validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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 'analyze document structure and provide insights' but doesn't specify what kind of insights, whether this is a read-only operation, if it modifies the document, what permissions are required, or any rate limits. For an analysis tool with zero annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with a clear purpose statement followed by parameter documentation. The two-sentence structure is efficient with zero wasted words. The parameter documentation uses a clean Args: format that's easy to parse. It could be slightly more front-loaded by moving the parameter details to a separate section.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists, the description doesn't need to explain return values. However, for a 2-parameter analysis tool with no annotations, the description should provide more context about what 'analyze' means in practice, what kind of insights are provided, and how this differs from simply retrieving the document. The parameter documentation helps, but the overall context remains somewhat incomplete.

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?

The description explicitly documents both parameters with their purposes: 'document_path: Path to the Markdown file' and 'validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"'. This adds substantial value beyond the input schema which has 0% description coverage. However, it doesn't explain the practical implications of different validation levels or provide examples of valid document paths.

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 clearly states the tool's purpose as 'Analyze document structure and provide insights' with a specific verb ('analyze') and resource ('document'). It distinguishes itself from siblings like 'get_document' (retrieval) or 'update_section' (modification) by focusing on analysis rather than basic CRUD operations. However, it doesn't explicitly differentiate from potential analysis-related siblings if they existed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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. With siblings like 'get_document' (retrieval), 'load_document' (loading), and 'list_sections' (listing), there's no indication whether this tool should be used instead of or in conjunction with them. The description lacks any 'when-to-use' or 'when-not-to-use' context.

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

delete_sectionC
        Delete a section by ID or heading.
        The document will be saved after the operation if successful and auto_save is True.
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
section_idNo
headingNo
auto_saveNo
backupNo
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

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 that the document will be saved if auto_save is True, which adds some context, but fails to disclose critical behavioral traits such as whether the deletion is permanent, what happens to nested sections, error conditions, or the impact of the backup and validation_level parameters. This leaves significant gaps 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences that are front-loaded with the core action. There is no wasted text, but it could be slightly more structured by explicitly listing key parameters or behaviors in a bullet-point format for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a destructive operation with 6 parameters, 0% schema description coverage, no annotations, and an output schema (which reduces the need to describe return values), the description is incomplete. It lacks details on parameter semantics, behavioral risks, and usage context, making it insufficient for safe and effective tool invocation.

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

Parameters2/5

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 by explaining parameters. It only mentions 'ID or heading' and 'auto_save', covering 2 out of 6 parameters (document_path, section_id, heading, auto_save, backup, validation_level). This partial coverage is inadequate, as key parameters like backup and validation_level are left unexplained, failing to add sufficient meaning beyond the schema.

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 clearly states the verb 'Delete' and the resource 'a section by ID or heading', making the purpose unambiguous. However, it doesn't explicitly distinguish this tool from sibling tools like 'move_section' or 'update_section' in terms of destructive nature, which would require 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 Guidelines2/5

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 'move_section' or 'update_section', nor does it mention prerequisites such as needing the document to be loaded first. It only mentions the auto_save condition, which is insufficient for comprehensive usage guidance.

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

get_documentB
        Get the complete document content and structure.
        
        Args:
            document_path: Path to the Markdown file
            validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

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 'complete document content and structure' and validation levels, but lacks details on permissions, rate limits, error handling, or what 'complete' entails (e.g., metadata, formatting). This leaves significant gaps in understanding the tool's behavior.

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 appropriately sized and front-loaded, with the core purpose stated first in a clear sentence, followed by parameter details in a structured format. Every sentence earns its place without redundancy or fluff, making it highly efficient for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

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 parameters, no annotations, but with an output schema), the description is minimally adequate. It covers the basic purpose and parameters but lacks behavioral context and usage guidelines. The presence of an output schema means return values needn't be explained, but overall completeness is limited.

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 description coverage is 0%, so the description must compensate. It adds meaning by explaining 'document_path' as 'Path to the Markdown file' and 'validation_level' with its allowed values and default, which clarifies beyond the bare schema. However, it doesn't detail path format or validation effects, preventing a perfect score.

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 clearly states the tool's purpose with the verb 'Get' and resource 'complete document content and structure', making it specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_section' or 'load_document', which limits its score to 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 'get_section' for partial content or 'load_document' which might have different semantics. Without any context or exclusions, the agent must infer usage from the name alone, which is insufficient for optimal tool selection.

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

get_sectionB
        Get a specific section by ID.
        
        Args:
            document_path: Path to the Markdown file
            section_id: The section ID to retrieve
            validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
section_idYes
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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 only states the basic action ('Get a specific section by ID') without mentioning any behavioral traits such as error handling, permissions required, rate limits, or what happens if the section doesn't exist. For a tool with no annotations, 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by a structured 'Args' section. There's no wasted text, and the information is organized efficiently. A 5 would require even more conciseness or bullet-point formatting, but this is very good.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there's an output schema (which handles return values), the description doesn't need to explain outputs. However, with 3 parameters, no annotations, and multiple sibling tools, the description is incomplete: it lacks usage guidelines and behavioral context. It's minimally adequate but has clear gaps, especially for a tool in a complex environment with many alternatives.

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?

The description adds meaningful semantics for all three parameters: it explains that 'document_path' is a 'Path to the Markdown file,' 'section_id' is 'The section ID to retrieve,' and 'validation_level' specifies 'Validation strictness' with enum values. Since schema description coverage is 0% (no schema descriptions), this fully compensates by providing clear parameter meanings beyond just the schema's titles and types.

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 clearly states the tool's purpose: 'Get a specific section by ID.' This is a specific verb+resource combination (get + section). However, it doesn't explicitly distinguish this tool from its siblings like 'get_document' or 'list_sections,' which would require 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 Guidelines2/5

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. There are multiple sibling tools for document/section operations (e.g., get_document, list_sections, update_section), but the description doesn't mention any of them or specify contexts where get_section is preferred. This leaves the agent without usage direction.

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

insert_sectionC
        Insert a new section at a specified location.
        The document will be saved after the operation if successful and auto_save is True.
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
headingYes
contentYes
positionYes
auto_saveNo
backupNo
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

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 the auto-save behavior, which is useful, but fails to cover critical aspects like required permissions, error handling, what happens if the position is invalid, or whether the operation is reversible. For a mutation tool with 7 parameters, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief and front-loaded with the main action, consisting of two sentences. However, the second sentence about auto-save could be more integrated, and overall it lacks the depth needed for a tool with 7 parameters, making it somewhat under-specified rather than optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (7 parameters, no annotations, but with an output schema), the description is incomplete. It doesn't address key contextual elements like what a 'section' entails, how 'position' is determined, or the implications of 'validation_level'. The presence of an output schema mitigates the need to describe return values, but other gaps remain significant.

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

Parameters2/5

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 by explaining parameters. It only references 'auto_save' indirectly, without detailing what it does or how it interacts with other parameters like 'backup' or 'validation_level'. The core parameters (document_path, heading, content, position) are not explained at all, leaving their purpose and format unclear.

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 clearly states the action ('Insert a new section') and the target ('at a specified location'), which distinguishes it from sibling tools like 'delete_section' or 'update_section'. However, it doesn't specify what kind of document or system it operates on, leaving some ambiguity about the resource context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions that the document is saved if 'auto_save is True', which provides some operational context, but it doesn't explain when to use this tool versus alternatives like 'update_section' or 'move_section'. No explicit guidance on prerequisites or exclusions is provided.

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

list_sectionsC
        List all sections in the document.
        
        Args:
            document_path: Path to the Markdown file
            validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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 'validation_level' but doesn't explain what validation entails (e.g., checking document format, handling errors) or the tool's behavior (e.g., returns a list, potential errors). This leaves significant gaps in understanding how the tool operates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with a clear purpose statement followed by parameter explanations in a structured 'Args' section. It avoids unnecessary fluff, though the formatting with extra whitespace slightly reduces efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

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 parameters, no annotations) and the presence of an output schema (which handles return values), the description is minimally adequate. It covers the basics but lacks details on behavioral traits, usage context, and full parameter semantics, making it incomplete for optimal agent understanding.

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 0%, so the description must compensate. It adds meaning by explaining 'document_path' as 'Path to the Markdown file' and 'validation_level' with its possible values, which clarifies beyond the bare schema. However, it doesn't detail the format of 'document_path' (e.g., relative/absolute) or the effects of different validation levels, leaving some ambiguity.

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 clearly states the verb 'List' and resource 'all sections in the document', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_section' or 'analyze_document', which would require a more detailed comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 'get_section' (for a single section) or 'analyze_document' (for broader analysis). It lacks context about prerequisites, such as whether the document must be loaded first, or exclusions for when not to use it.

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

load_documentB
        Load and analyze a Markdown document from a file path.
        
        Args:
            document_path: Path to the Markdown file (supports absolute, relative, and ~ expansion)
            validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

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 tool loads and analyzes a document, implying read-only operations, but doesn't disclose critical behaviors such as error handling (e.g., what happens if the file doesn't exist), performance aspects (e.g., file size limits), or analysis specifics (e.g., what 'analyze' entails). This leaves significant 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose ('Load and analyze a Markdown document from a file path') followed by parameter details in a structured 'Args' section. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

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 parameters, no annotations, but with an output schema), the description is partially complete. It covers the purpose and parameters well, but lacks behavioral context (e.g., error handling, analysis output) and usage guidelines. The presence of an output schema means return values are documented elsewhere, so the description doesn't need to explain them, but overall gaps in transparency and guidelines reduce completeness.

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?

The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'document_path' supports 'absolute, relative, and ~ expansion', clarifying usage beyond the schema's generic 'string' type, and defines 'validation_level' options ('STRICT', 'NORMAL', 'PERMISSIVE') with a default implied by 'NORMAL' in the schema. This compensates well for the low schema coverage, though it doesn't detail what each validation level means.

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 clearly states the tool's purpose with specific verbs ('load and analyze') and resource ('Markdown document from a file path'), distinguishing it from siblings like 'get_document' (which likely retrieves without analysis) or 'analyze_document' (which may analyze without loading). However, it doesn't explicitly differentiate from 'get_document' in terms of loading vs. retrieving, leaving some ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 'get_document' or 'analyze_document'. It mentions loading and analyzing, but doesn't specify prerequisites (e.g., file existence), exclusions, or comparative contexts with sibling tools, leaving the agent to infer usage scenarios.

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

move_sectionC
        Move a section to a different position.
        The document will be saved after the operation if successful and auto_save is True.
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
section_idYes
target_positionYes
auto_saveNo
backupNo
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

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 that the document is saved if successful and auto_save is True, which hints at mutation and persistence behavior. However, it fails to address critical aspects like permissions needed, whether the operation is reversible, error handling, or what 'successful' entails, leaving significant gaps for a tool with 6 parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief and front-loaded with the core action in the first sentence, followed by a conditional detail. It avoids unnecessary verbosity, but the second sentence could be integrated more smoothly for better flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, mutation operation) and the presence of an output schema, the description is incomplete. It lacks details on parameter semantics, behavioral traits like error handling or side effects, and does not leverage the output schema to explain return values. For a tool with no annotations and low schema coverage, this is inadequate.

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

Parameters2/5

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 for undocumented parameters. It only references 'auto_save' implicitly, without explaining other parameters like 'document_path', 'section_id', 'target_position', 'backup', or 'validation_level'. This adds minimal value beyond the schema, failing to clarify parameter meanings or usage.

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 clearly states the action ('Move a section') and the resource ('section'), specifying the operation's goal ('to a different position'). It distinguishes from siblings like 'delete_section' or 'update_section' by focusing on repositioning, but does not explicitly contrast with 'insert_section' or 'list_sections' in terms of scope or function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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_section' for content changes or 'insert_section' for adding new sections. It mentions auto-save behavior but lacks context on prerequisites, error conditions, or typical use cases relative to sibling tools.

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

save_documentA
        Save the document (mainly for validation purposes since auto_save handles most cases).
        
        Args:
            document_path: Path to the source Markdown file
            target_path: Path to save to (if different from source)
            backup: Whether to create a backup before saving
            validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
target_pathNo
backupNo
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It mentions validation purposes and backup behavior, which adds useful context. However, it lacks details on permissions needed, error handling, rate limits, or what happens if validation fails. The description doesn't contradict any annotations (none provided).

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 well-structured and front-loaded: the first sentence states the purpose and context, followed by a clear Args section. Every sentence earns its place with no wasted words. It's appropriately sized for a 4-parameter tool.

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?

Given the tool has an output schema (not shown here), the description doesn't need to explain return values. It covers the purpose, usage context, and parameter semantics adequately. However, as a mutation tool with no annotations, it could benefit from more behavioral details like error conditions or side effects.

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 description coverage is 0%, so the description must compensate. It provides clear explanations for all 4 parameters: 'document_path' (source), 'target_path' (save destination), 'backup' (create backup), and 'validation_level' (strictness with enum values). This adds significant meaning beyond the bare schema, though it could elaborate on default behaviors.

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 clearly states the verb ('Save') and resource ('the document'), and specifies it's 'mainly for validation purposes since auto_save handles most cases.' This distinguishes it from simple save operations. However, it doesn't explicitly differentiate from sibling tools like 'update_section' or 'move_section' 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: 'mainly for validation purposes since auto_save handles most cases.' This gives guidance on when to use this tool (for validation) versus relying on auto-save. However, it doesn't explicitly mention alternatives among sibling tools or when not to use it.

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

update_sectionC
        Update the content of an existing section.
        The document will be saved after the operation if successful and auto_save is True.
ParametersJSON Schema
NameRequiredDescriptionDefault
document_pathYes
section_idYes
contentYes
auto_saveNo
backupNo
validation_levelNoNORMAL

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

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 that 'The document will be saved after the operation if successful and auto_save is True', which adds some context about saving behavior. However, it fails to disclose critical traits like whether this is a destructive mutation, what permissions are required, error handling, or rate limits, leaving significant gaps for a tool that modifies content.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences that are front-loaded: the first states the core purpose, and the second adds behavioral context. There is no wasted text, and it avoids unnecessary elaboration, making it efficient and well-structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a mutation tool with 6 parameters, 0% schema coverage, no annotations, and sibling tools, the description is incomplete. It lacks details on parameter usage, error conditions, permissions, and how it differs from alternatives. While an output schema exists (which might cover return values), the description does not provide enough context for safe and effective tool invocation in this environment.

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

Parameters2/5

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 by explaining parameters. It only mentions 'auto_save' implicitly in the context of saving behavior, but does not describe the purpose or usage of other parameters like 'document_path', 'section_id', 'content', 'backup', or 'validation_level'. This leaves most parameters undocumented, failing to add meaningful semantics beyond the bare schema.

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 clearly states the verb 'update' and the resource 'content of an existing section', making the purpose specific and understandable. It distinguishes from siblings like 'insert_section' (create new) and 'delete_section' (remove), though it doesn't explicitly name these alternatives. The purpose is not vague or tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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_section' or 'move_section', nor does it mention prerequisites such as needing an existing document or section. It only implies usage through the phrase 'existing section', but lacks explicit context or exclusions for tool selection.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 10 tool updates
    • First observedanalyze_document
    • First observeddelete_section
    • First observedget_document
    • First observedget_section
    • First observedinsert_section
    • First observedlist_sections
    • First observedload_document
    • First observedmove_section
    • First observedsave_document
    • First observedupdate_section
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation4/5

Most tools have distinct purposes targeting different document operations, but there is some overlap between get_document and load_document where both retrieve document content. The descriptions clarify that load_document includes analysis while get_document focuses on content/structure, but an agent might initially confuse them.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with snake_case naming (e.g., analyze_document, delete_section, get_document). The verbs are clear and appropriate for the actions, making the tool set predictable and readable.

Tool Count5/5

With 10 tools, this is well-scoped for a Markdown editor server, covering core operations like loading, analyzing, reading, writing, and manipulating sections. Each tool has a clear role without unnecessary duplication, fitting typical server sizes.

Completeness5/5

The tool set provides comprehensive coverage for document management, including CRUD operations for sections (list, get, insert, update, delete, move) and full document handling (load, get, analyze, save). There are no obvious gaps for the domain of editing and analyzing Markdown files.

Maintenance

ActivityInactive
ResponsivenessSyncing

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

Related MCP Servers

  • Tiptap Collaboration MCP

    trainual
    A
    license
    A
    quality
    C
    maintenance
    Enables interaction with Tiptap collaborative document services through comprehensive document management, real-time statistics, markdown conversion, and batch operations. Supports creating, updating, searching, and managing collaborative documents with health monitoring and semantic search capabilities.
    14
    11
    MIT

  • Markdown Editor MCP Server

    KazKozDev
    A
    license
    C
    quality
    Not graded
    maintenance
    Provides semantic editing tools for Markdown files, allowing structured manipulation of document elements through hierarchical paths rather than raw text operations. Supports navigation, search, content replacement, element insertion/deletion, undo functionality, and YAML frontmatter management.
    15
    2
    -

Latest Blog Posts

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/quantalogic/quantalogic_markdown_mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server