Enables AI assistants to read, create, update, and manage encrypted markdown documents and workspaces, allowing markdown files to be organized into an LLM-accessible knowledge base with support for partial fetches and version control.
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., "@molt-mcp read the latest meeting notes from my workspace"
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.
A Model Context Protocol (MCP) server that provides LLM access to molt-md, an encrypted markdown document hosting service. Turn your markdown files into an LLM-accessible knowledge base by uploading them to molt-md and accessing them through this MCP server. Your AI assistant can read, update, and manage encrypted markdown documents organized in workspaces.
Markdown → MCP Server - Organize your markdown files into LLM-accessible storage with workspaces (free while in beta)
Full API Coverage - Every molt-md endpoint exposed as an MCP tool
Encrypted Storage - End-to-end encryption with AES-256-GCM
Read/Write Key Support - Permission enforcement via the API's dual-key model
Workspace Management - Bundle and organize multiple documents
Partial Fetches - Efficient document previews with line-limited reads
Version Control - Optimistic concurrency control with ETag support
Related MCP server: MinerU Document Explorer
Install directly from GitHub using uvx:
uvx --from git+https://github.com/bndkts/molt-md-mcp molt-mcpOr install from source for development:
git clone https://github.com/bndkts/molt-md-mcp.git
cd molt-md-mcp
uv pip install -e .Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"molt-md": {
"command": "uvx",
"args": ["--from", "git+https://github.com/bndkts/molt-md-mcp", "molt-mcp"],
"env": {
"MOLT_API_KEY": "your-api-key-here",
"MOLT_WORKSPACE_ID": "your-workspace-id-here"
}
}
}
}MOLT_API_KEY (required) - Your molt-md write key or read key (obtained by creating a document)
MOLT_WORKSPACE_ID (optional) - Access documents through a specific workspace
MOLT_BASE_URL (optional) - API base URL (defaults to https://api.molt-md.com/api/v1; use http://localhost:8000/api/v1 for local development)
The server passes your configured key to the molt-md API on every request:
Write key → All operations succeed (read + create + update + delete)
Read key → Read operations succeed; write operations return 403 Forbidden from the API
health_check - Check if the molt-md API is available
get_metrics - Get database statistics (document and workspace counts)
read_doc - Read a document's decrypted content
Supports partial fetches with lines parameter
Returns JSON with metadata or plain markdown
read_workspace - Read a workspace's content (name and entries)
Supports preview generation with preview_lines parameter
create_doc - Create a new encrypted document
Returns document ID, write key, and read key
update_doc - Replace a document's entire content
Supports optimistic locking with if_match (version ETag)
append_doc - Append content to the end of a document
Supports optimistic locking with if_match
delete_doc - Permanently delete a document
create_workspace - Create a new workspace to bundle documents
Returns workspace ID, write key, and read key
update_workspace - Replace a workspace's content (name and entries)
Supports optimistic locking with if_match
delete_workspace - Permanently delete a workspace
Does not delete referenced documents
User: Create a new document with the title "Meeting Notes"
Assistant: [Uses create_doc tool] → Returns doc ID and keys
User: Read that document
Assistant: [Uses read_doc tool with the doc ID]
User: Append a new section to the document
Assistant: [Uses append_doc tool]User: Create a workspace called "Project Alpha" with these two documents
Assistant: [Uses create_workspace tool with document IDs and keys]
User: Show me a preview of all documents in the workspace
Assistant: [Uses read_workspace with preview_lines=1]User: Show me just the title of document xyz
Assistant: [Uses read_doc with lines=1 and as_markdown=true]# Clone the repository
git clone https://github.com/bndkts/molt-md-mcp.git
cd molt-md-mcp
# Install dependencies
uv pip install -e .
# Run the server
molt-mcpWith local molt-md API:
# Start the molt-md API server first (in another terminal)
cd /path/to/molt-md
cargo run # or your preferred method
# Create a test document to get keys
curl -X POST http://localhost:8000/api/v1/docs \
-H "Content-Type: application/json" \
-d '{"content": "# Test Document"}'
# Save the write_key and id from the response
# Run the MCP server
export MOLT_BASE_URL="http://localhost:8000/api/v1"
export MOLT_API_KEY="your-write-key-here"
npx @modelcontextprotocol/inspector molt-mcpWith production molt-md API:
# Create a test document to get keys
curl -X POST https://api.molt-md.com/api/v1/docs \
-H "Content-Type: application/json" \
-d '{"content": "# Test Document"}'
# Save the write_key from the response
# Run the MCP server
export MOLT_API_KEY="your-write-key-here"
npx @modelcontextprotocol/inspector molt-mcpNever commit API keys to version control
Keys are shown only once during document/workspace creation - save them securely
Read keys can be safely shared for read-only collaborators
Write keys provide full access - share only with trusted editors
Lost keys cannot be recovered - the content becomes permanently inaccessible
This is a thin wrapper around the molt-md REST API:
FastMCP handles the MCP protocol and tool registration
httpx makes async HTTP requests with connection pooling
Environment config provides API key and optional workspace context
UUID validation and ETag formatting ensure correct API usage
molt-md: https://molt-md.com
MCP Specification: https://modelcontextprotocol.io
FastMCP: https://github.com/jlowin/fastmcp
MIT License - see LICENSE file for details
Contributions are welcome! Please open an issue or pull request on GitHub.
Built with ❤️ for the Model Context Protocol ecosystem
Append content to the end of a document (separated by newline). Requires write key. The API will return 403 if a read key is used.
Args: doc_id: UUID of the document to append to content: Markdown content to append if_match: Optional - version ETag (e.g., 'v5') to prevent conflicts
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| content | Yes | ||
| if_match | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and discloses: mutation behavior (append with newline separator), authentication requirements (write key), and specific error conditions (403 for read keys). Minor gap: does not describe behavior when document ID is not found.
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?
Front-loaded with action and constraints, followed by structured Args section. No wasted words; every sentence provides essential information about behavior, auth, or parameter semantics.
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?
Complete for a 3-parameter tool with an output schema (which exempts it from describing return values). All parameters documented, auth covered. Minor deduction for not mentioning potential 404 errors or explicit sibling differentiation.
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 coverage is 0%, but the description comprehensively documents all three parameters: doc_id ('UUID of the document'), content ('Markdown content'), and if_match ('version ETag to prevent conflicts'). Fully compensates for the bare schema.
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?
Description provides specific verb (append), resource (document), and scope (end of document, separated by newline). This clearly distinguishes it from sibling 'update_doc' (general modification) and 'create_doc' (new document creation).
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?
Explicitly states authentication requirements ('Requires write key. The API will return 403 if a read key is used'), providing clear prerequisites for usage. However, it does not explicitly state when to prefer this over 'update_doc' (append vs. replace scenarios).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new encrypted document. Returns the document ID and both write and read keys. IMPORTANT: Save these keys - they are shown only once!
Args: content: Initial markdown content for the document (optional)
| Name | Required | Description | Default |
|---|---|---|---|
| content | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It successfully discloses the return structure (document ID, write/read keys) and the critical behavioral constraint that keys are ephemeral ('shown only once'), though it omits other potential behavioral details like rate limits or permissions.
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?
Every sentence earns its place: the first defines the action, the second states the return values, the third provides a critical warning, and the Args section documents the single parameter. No redundancy or fluff.
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 only one parameter and an output schema exists, the description is appropriately complete. It covers the essential behavioral warning (one-time keys) and parameter semantics without needing to exhaustively document return values that the output schema should define.
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?
With 0% schema description coverage, the description compensates effectively by specifying that the content parameter accepts 'Initial markdown content' and is 'optional', providing type context and requirement status absent from the schema.
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 ('Create') and resource ('encrypted document'), immediately distinguishing it from sibling tools like read_doc, update_doc, or append_doc which handle existing documents.
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?
While it doesn't explicitly name alternatives (e.g., 'use update_doc for modifications'), the description provides critical usage context by specifying that keys are shown only once and must be saved immediately, implying this is an initialization operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new encrypted workspace to bundle multiple documents. Returns the workspace ID and both write and read keys. IMPORTANT: Save these keys - they are shown only once!
Args: name: Human-readable workspace name entries: Optional list of entries. Each entry should have: - type: "md" for documents or "workspace" for sub-workspaces - id: UUID of the document/workspace - key: Write or read key for the item
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| entries | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden and succeeds in disclosing critical behavior: the workspace is encrypted, and keys are displayed only once (flagged as 'IMPORTANT'). However, it omits details on failure modes, idempotency, or permissions required for the entries parameter keys.
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 efficiently structured with clear information hierarchy: purpose statement, return value summary, critical warning (front-loaded), then detailed Args documentation. Every sentence serves a distinct purpose with no redundant filler.
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 presence of an output schema, the description appropriately summarizes returns (workspace ID and keys) without redundancy. It adequately documents the 2 parameters despite poor schema coverage and warns about the irreversible key disclosure. Minor gaps remain regarding error handling and duplicate name behavior.
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?
With 0% schema description coverage, the description fully compensates by documenting both parameters in the Args section. It adds crucial semantic constraints for 'entries' (specifying required fields: type with allowed values 'md'/'workspace', id as UUID, and key types) that the loose schema (additionalProperties: string) fails to capture.
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 opens with a specific verb ('Create') and resource ('workspace'), immediately clarifying the tool creates encrypted containers for bundling documents. The 'encrypted' and 'bundle multiple documents' qualifiers effectively distinguish this from create_doc and other sibling 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?
While the description explains what the tool does (bundling documents), it lacks explicit guidance on when to prefer this over create_doc or when to use update_workspace instead. Usage is implied by the 'bundle multiple documents' phrase but no explicit comparisons or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a document. This action cannot be undone. Requires write key. The API will return 403 if a read key is used.
Args: doc_id: UUID of the document to delete
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 and succeeds by stating 'This action cannot be undone' to indicate destructive irreversibility, and specifying authentication requirements and error responses (403). It appropriately warns about the permanent nature of the operation that would typically be indicated by a destructiveHint annotation.
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 efficiently organizes four sentences covering the action, irreversibility warning, authentication requirements, and error conditions without redundancy. The addition of an 'Args:' section to document the parameter is appropriate given the schema's lack of descriptions, ensuring all necessary information is conveyed compactly.
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 single-parameter simplicity and the presence of an output schema (meaning return values need not be described), the description adequately covers the operation's purpose, destructive implications, and authorization constraints. No significant gaps remain for an agent to understand when and how to invoke this tool safely.
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 provides 0% description coverage for the doc_id parameter, offering only type information. The description compensates by specifying that the parameter is a 'UUID' and defining it as 'the document to delete,' adding essential semantic meaning missing from the schema.
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 explicitly states the specific action 'Permanently delete a document,' combining a clear verb with the resource type. It effectively distinguishes from siblings like delete_workspace (by specifying 'document') and from read_doc/update_doc (by emphasizing the permanent deletion aspect).
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 explicit authorization context stating 'Requires write key' and warns that 'The API will return 403 if a read key is used,' establishing clear prerequisites for safe invocation. While it does not explicitly name alternatives like update_doc for non-destructive modifications, it effectively communicates the permission requirements and constraints for proper use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a workspace. This action cannot be undone. Referenced documents and sub-workspaces are NOT deleted. Requires write key. The API will return 403 if a read key is used.
Args: workspace_id: UUID of the workspace to delete
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It effectively communicates destructiveness ('Permanently delete', 'cannot be undone'), scope limitations (what is NOT deleted), and authorization requirements. It does not mention idempotency or specific error conditions beyond the 403, preventing a perfect score.
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 tightly structured with four high-information sentences followed by a clear Args section. Critical information (permanence, irreversibility) is front-loaded, and there is no redundant or wasted language.
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 (per context signals), the description appropriately focuses on behavioral semantics rather than return values. It covers auth, scope, and destructiveness adequately for a single-parameter deletion tool, though it could explicitly mention what successful deletion returns.
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 0% description coverage (only title and type). The description compensates by documenting the single parameter in the Args section, specifying it is a 'UUID' and identifying it as the 'workspace to delete', adding critical type and semantic information absent from the schema.
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 ('Permanently delete') and resource ('workspace'), and explicitly distinguishes the scope from sibling tools by clarifying that 'Referenced documents and sub-workspaces are NOT deleted' (differentiating from delete_doc and indicating non-cascading behavior).
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?
Provides explicit prerequisites ('Requires write key') and failure modes ('The API will return 403 if a read key is used'), which constrains when the tool can be successfully invoked. While it doesn't explicitly name alternative tools like read_workspace, the auth requirements provide clear usage constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get database statistics (total documents and workspaces count).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The verb 'Get' and mention of 'statistics' implies a read-only operation, but the description omits details about whether counts are real-time or cached, performance characteristics, or if the operation is idempotent. It provides basic behavioral context (what data is accessed) but lacks operational details.
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?
Single sentence of seven words with zero redundancy. Information is front-loaded and dense, efficiently conveying the exact scope of the operation without unnecessary filler.
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 zero parameters, an output schema exists (covering return value documentation), and the operation is conceptually simple, the description provides complete context. The specific mention of 'documents and workspaces' aligns with the sibling tool ecosystem, providing sufficient context for selection.
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 zero parameters, establishing a baseline of 4. With no parameters to describe, there is no additional semantic information required from the description, and none is provided.
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?
Description uses specific verb 'Get' with clear resource 'database statistics' and explicitly details scope (total documents and workspaces count). This clearly distinguishes it from sibling CRUD tools (read_doc, read_workspace) which retrieve individual items, and from health_check which checks system status rather than content metrics.
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 implies usage context by specifying aggregate counts, suggesting it should be used when needing statistics rather than individual documents. However, it lacks explicit when-to-use guidance or comparisons to alternatives (e.g., when to use this vs. iterating through read_workspace to count manually).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if the molt-md API is available and responding.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full disclosure burden. It states what gets checked (availability/responding) but omits safety profile (read-only, idempotent), authentication requirements, rate limits, or timeout behavior. Output schema exists, so return value documentation is not required in 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?
Single sentence with zero waste. Front-loaded with action verb. Appropriate length for zero-parameter health check utility.
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?
Low complexity tool (zero parameters, boolean/simple return). Output schema exists to document return values. Description adequately covers the tool's sole purpose without unnecessary elaboration.
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?
Zero parameters per input schema (schema coverage 100%). With no parameters to document, baseline score of 4 applies per rubric ('0 params = baseline 4'). Description correctly implies no arguments needed.
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?
Description uses specific verb 'Check' with clear resource 'molt-md API' and scope 'available and responding'. Distinct from all CRUD siblings (create_doc, update_workspace, etc.) and differentiates from get_metrics by focusing on availability rather than performance metrics.
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 when-to-use or when-not-to-use guidance provided. While the tool's purpose is self-evident from the name, description does not clarify relationship to sibling 'get_metrics' (health vs. metrics) or suggest prerequisite usage (e.g., 'call before operations'). Usage remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a document's decrypted content.
Args: doc_id: UUID of the document to read lines: Optional - return only the first N lines (for previews) as_markdown: If True, return plain markdown; if False, return JSON with metadata
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| lines | No | ||
| as_markdown | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses key behavioral traits: decryption occurs during reading, and output format varies (markdown vs JSON with metadata) based on as_markdown flag. However, it omits safety profile (idempotency, read-only nature), error conditions, or authorization requirements.
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 appropriately sized with zero waste. The Args section structure efficiently maps parameters to their semantics. The front-loaded first sentence establishes purpose immediately. Minor deduction for informal docstring formatting ('Args:') which is slightly less readable than prose.
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 presence of an output schema (not shown but indicated in context signals), the description appropriately focuses on input parameters and high-level behavior rather than return values. For a 3-parameter read operation with decryption complexity, the description covers the essential contract adequately.
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?
With 0% schema description coverage (no description fields in the JSON schema), the description effectively compensates by documenting all three parameters: doc_id as 'UUID', lines as 'Optional - return only the first N lines', and as_markdown behavior. This provides essential semantic context missing from the structured schema.
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 'Read[s] a document's decrypted content'—specific verb (read), specific resource (document), and unique scope (decrypted content). This distinguishes it from siblings like create_doc or update_doc, though it doesn't explicitly contrast with read_workspace.
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 explicit guidance on when to use this tool versus alternatives (e.g., when to use lines parameter for previews vs full read). The phrase 'for previews' implies a use case for the lines parameter but doesn't constitute explicit when/when-not guidance for the tool itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a workspace's decrypted content (name and entries).
Args: workspace_id: UUID of the workspace to read preview_lines: Optional - include preview of first N lines for each document entry
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | ||
| preview_lines | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses 'decrypted content' which is important behavioral context, but lacks disclosure of safety (read-only vs mutation), side effects, error conditions, or rate limits that would help an agent understand operational risks.
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?
Uses structured Args format that efficiently presents parameter semantics without prose bloat. Two-sentence preamble plus Args block is appropriately sized for a 2-parameter tool; no redundant or filler text.
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?
For a read operation with 2 parameters and an existing output schema, the description adequately covers the tool's purpose, the decryption behavior, and all parameters. No critical gaps given the relatively simple operation scope.
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 has 0% description coverage, but the Args section compensates effectively by documenting workspace_id as 'UUID of the workspace to read' and explaining that preview_lines 'include[s] preview of first N lines for each document entry'—adding clear semantic meaning beyond raw types.
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 uses specific verb 'Read' with clear resource 'workspace's decrypted content' and specifies returned data (name and entries). It distinguishes from siblings like read_doc (individual documents) and update_workspace through explicit 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?
No guidance provided on when to use this versus read_doc (which also reads content) or versus other workspace operations. No prerequisites or alternatives mentioned despite having multiple related sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a document's entire content with new content. Requires write key. The API will return 403 if a read key is used.
Args: doc_id: UUID of the document to update content: New markdown content (replaces existing content) if_match: Optional - version ETag (e.g., 'v5') to prevent conflicts
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| content | Yes | ||
| if_match | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and discloses critical behavioral traits: authentication requirements (write key), error conditions (403), and concurrency control (if_match ETag for conflict prevention). It implies destructiveness via 'replaces existing content' but could explicitly state that original content is permanently lost.
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?
Three concise sentences front-load the purpose, auth requirements, and error handling, followed by a structured Args block. Every element serves a distinct purpose; no redundancy or filler text is present despite documenting three parameters and auth constraints.
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 presence of an output schema, the description appropriately omits return value details. It comprehensively covers the 3 parameters (compensating for zero schema coverage) and auth requirements. Minor gap: could explicitly clarify the destructive nature of the operation relative to sibling append_doc.
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 0% description coverage (titles only), but the description fully compensates via the Args section. It adds crucial semantics: doc_id is a 'UUID', content is 'markdown' format, and if_match is a 'version ETag' for conflict prevention—information entirely absent from the schema.
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 opens with the specific action 'Replace' and clearly identifies the resource ('document') and scope ('entire content'). It effectively distinguishes from siblings like append_doc (partial addition) and read_doc (read-only access) through the explicit 'replace entire content' phrasing.
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?
Provides clear prerequisites ('Requires write key') and failure modes ('API will return 403 if a read key is used'), establishing when the tool can be used. However, it does not explicitly differentiate from append_doc regarding when to prefer partial updates versus full replacement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a workspace's entire content (name and entries). Requires write key. The API will return 403 if a read key is used.
Args: workspace_id: UUID of the workspace to update name: New workspace name entries: New list of entries (replaces existing entries) if_match: Optional - version ETag (e.g., 'v1') to prevent conflicts
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | ||
| name | Yes | ||
| entries | Yes | ||
| if_match | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It effectively discloses the destructive nature ('replaces existing entries'), authentication requirements, and concurrency control mechanism ('if_match... to prevent conflicts'). It does not mention idempotency or atomicity guarantees, but the output schema handles return value documentation.
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 well-structured with high information density. The two-sentence preamble front-loads critical information (operation type and auth requirements). The Args section follows logically, with no redundant or wasteful text.
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 0% schema coverage and the tool's complexity (destructive mutation, auth-gated, concurrency-controlled), the description successfully documents all parameters and behavioral risks. A perfect score would require explicit mention of atomicity or rollback behavior, but the coverage is sufficient for safe 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?
With 0% schema description coverage, the description fully compensates by documenting all 4 parameters in the Args section. It adds critical behavioral context beyond types: 'entries' is explained as replacing existing data, and 'if_match' includes an example value ('v1') and explains its purpose (conflict prevention).
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 opens with a specific verb ('Replace') and clearly identifies the resource ('workspace') and scope ('entire content', 'name and entries'). It effectively distinguishes from siblings like read_workspace (read vs. replace), create_workspace (create vs. update), and delete_workspace (delete vs. modify).
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 clear authentication requirements ('Requires write key') and error conditions ('API will return 403 if a read key is used'), which are critical usage constraints. However, it does not explicitly state when to use this versus create_workspace or whether this is preferred over delete+create patterns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0append_doccreate_doccreate_workspacedelete_docdelete_workspaceget_metricshealth_checkread_docread_workspaceupdate_docupdate_workspaceScored across 11 tools
Every tool has a clearly distinct purpose with no ambiguity. Document operations (create, read, update, delete, append) and workspace operations (create, read, update, delete) are cleanly separated, while get_metrics and health_check serve unique administrative functions. The descriptions clearly differentiate between similar-sounding tools like update_doc vs append_doc.
All tools follow a consistent verb_noun pattern with snake_case throughout. Document tools use create/read/update/delete/append_doc, workspace tools use create/read/update/delete_workspace, and administrative tools use get_metrics and health_check. There are no deviations in naming conventions.
With 11 tools, this is well-scoped for a document/workspace management system. The count provides complete CRUD operations for both documents and workspaces, plus append functionality for documents and essential administrative tools. Each tool earns its place without redundancy.
The tool surface provides complete coverage for document and workspace management. For documents: create, read, update, delete, and append operations cover the full lifecycle. For workspaces: create, read, update, and delete operations. Administrative tools (health_check, get_metrics) provide necessary monitoring. No obvious gaps exist for this domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
Instant markdown sharing. Create, manage, and share documents with password protection.
Create, edit, review, and explicitly publish Live or Snapshot Markdown Documents in mdedit.ai.
