Click on "Deploy 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., "@OfficeReader-MCP convert my presentation at /home/user/slides.pptx to markdown with images"
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 converts Microsoft Office documents (Word, Excel, PowerPoint) to Markdown format with intelligent image extraction and optimization.
Multi-Format Support: Word (.docx, .doc), Excel (.xlsx, .xls), PowerPoint (.pptx, .ppt)
Intelligent Image Processing: Automatic extraction and optimization with WebP compression
Format Preservation: Maintains document structure including headings, tables, lists, and formatting
Metadata Extraction: Access document properties (author, title, creation date, etc.)
Efficient Caching: Smart caching system for quick reuse of converted documents
Cross-Platform: Works on Windows, macOS, and Linux
Related MCP server: MCP Document Converter
Format | Extensions | Features |
Word |
| Text formatting, headings, lists, tables, images |
Excel |
| Multi-sheet support, tables, charts, embedded images |
PowerPoint |
| Slides, text boxes, images, speaker notes, tables |
Python 3.10 or higher
Claude Desktop or Claude Code
# Clone the repository
git clone https://github.com/Asunainlove/office-reader-mcp.git
cd office-reader-mcp
# Install in editable mode
pip install -e .Add to your Claude Desktop config file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS/Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"officereader": {
"command": "python",
"args": ["-m", "officereader_mcp.server"],
"env": {
"OFFICEREADER_CACHE_DIR": "/path/to/cache"
}
}
}
}Add to your Claude Code settings:
Windows: %LOCALAPPDATA%\claude-code\settings.json
macOS/Linux: ~/.config/claude-code/settings.json
{
"mcpServers": {
"officereader": {
"command": "python",
"args": ["-m", "officereader_mcp.server"],
"env": {
"OFFICEREADER_CACHE_DIR": "/path/to/cache"
}
}
}
}Restart Claude Desktop or Claude Code to load the MCP server.
After installation, you can use OfficeReader-MCP directly in your conversations with Claude:
Convert my Excel file at D:\Reports\sales_2024.xlsx to markdownExtract text and images from D:\Presentations\keynote.pptxGet metadata from my document at C:\Documents\report.docxconvert_documentConvert any supported Office document to Markdown format.
Parameters:
file_path (required): Absolute path to the document
extract_images (optional, default: true): Extract embedded images
image_format (optional, default: "file"): How to handle images
"file": Save images to disk (recommended)
"base64": Embed images as base64 in markdown
"both": Both save and embed
output_name (optional): Custom name for output files
Example:
Convert D:\Documents\report.xlsx with imagesread_converted_markdownRead the full content of a previously converted markdown file.
Parameters:
markdown_path (required): Path to the markdown file
Example:
Read the markdown at D:\cache\output\report_abc12345\report_abc12345.mdlist_conversionsList all cached document conversions with details.
Example:
List all converted documentsclear_cacheClear all cached conversions to free up disk space.
Example:
Clear the document cacheget_document_metadataExtract metadata from a document without full conversion (faster).
Parameters:
file_path (required): Path to the document
Example:
Get metadata from D:\Documents\presentation.pptxget_supported_formatsGet list of all supported file formats and extensions.
Example:
What file formats does officereader support?Converted documents are organized in the cache directory:
cache/
└── output/
└── document_name_abc12345/
├── document_name_abc12345.md # Converted markdown
└── images/
├── image_001.webp # Optimized images
├── slide2_image_002.webp
└── excel_image_003.webpImages are automatically optimized to reduce file size while maintaining quality:
Max Dimensions: 1920×1080 pixels (configurable)
Format: WebP (preferred) or PNG/JPEG fallback
Quality: 80% for photos, 85% for JPEG, lossless PNG for graphics with transparency
Typical Compression: 50-80% size reduction
Smart Detection: Automatically distinguishes between photos and graphics
OfficeReader-MCP/
├── src/officereader_mcp/
│ ├── server.py # MCP server implementation
│ ├── converter.py # Word converter (DocxConverter, OfficeConverter)
│ ├── excel_converter.py # Excel to Markdown converter
│ ├── pptx_converter.py # PowerPoint to Markdown converter
│ ├── image_optimizer.py # Image compression utility
│ └── __init__.py # Package initialization
├── test/
│ ├── test_converter.py # Basic functionality tests
│ └── test_all_formats.py # Comprehensive test suite
├── pyproject.toml # Project configuration
└── README.md # DocumentationPackage | Version | Purpose |
| >=1.0.0 | Model Context Protocol SDK |
| >=1.1.0 | DOCX file parsing and manipulation |
| >=1.6.0 | DOC/DOCX to HTML conversion (fallback) |
| >=10.0.0 | Image processing and optimization |
| >=0.11.0 | HTML to Markdown conversion |
| >=3.1.0 | Excel file parsing |
| >=0.6.21 | PowerPoint file parsing |
All dependencies are automatically installed when you run pip install -e .
# Basic converter test
python test/test_converter.py
# Comprehensive test suite for all formats
python test/test_all_formats.py
# Test with a specific document
python test/test_converter.py path/to/your/document.docxThe test suite verifies:
Module imports and initialization
Converter functionality for all formats
Image extraction and optimization
File type detection
Cache management
Metadata extraction
OfficeReader-MCP supports multiple configuration methods to customize cache locations and behavior.
Copy the example config file:
cp config.example.json config.jsonEdit config.json to set your cache directory:
{
"cache_dir": "D:/MyDocuments/OfficeReaderCache",
"image_optimization": {
"enabled": true,
"max_dimension": 1920,
"quality": 80
}
}The config file will be automatically loaded on startup.
For detailed configuration options, see CONFIG.md.
Variable | Description | Default |
| Directory for cached conversions | System temp directory |
Example usage:
# Set custom cache directory
export OFFICEREADER_CACHE_DIR=/path/to/custom/cache
# Or in Windows
set OFFICEREADER_CACHE_DIR=C:\path\to\custom\cacheNote: Environment variables take priority over config file settings.
User: Convert my Excel file at D:\Reports\Q4_sales.xlsx
Claude: I'll convert that Excel file. Each sheet will be converted to a separate
section in the markdown with properly formatted tables...
[Output includes all sheets as markdown tables with preserved formatting]User: Extract all text and images from D:\Presentations\product_launch.pptx
Claude: Converting the PowerPoint presentation. I'll extract text from each slide,
including speaker notes, along with all embedded images...
[Output includes slide-by-slide breakdown with images and notes]User: Convert all Office documents in D:\Documents\
Claude: I'll convert each document and cache the results for quick access...
[Processes all supported files and provides summary]# Reinstall the package
pip install -e .Verify the config file location is correct
Check JSON syntax is valid (use a JSON validator)
Restart Claude Desktop or Claude Code completely
Check logs for error messages
Possible causes:
Document contains linked images (not embedded)
Insufficient write permissions for cache directory
Image format not supported by the document library
Solution:
# Verify cache directory is writable
ls -la /path/to/cache # Unix/Mac
dir /path/to/cache # Windows
# Check if images are embedded
# Use convert_document with extract_images=true explicitlyThe converter uses UTF-8 encoding throughout. If you see garbled text:
Check the source document encoding
Ensure your terminal/console supports UTF-8
Try converting with different system locale settings
Major Features:
Added Excel (.xlsx, .xls) support with multi-sheet conversion
Added PowerPoint (.pptx, .ppt) support with slide extraction
Implemented intelligent image optimization with WebP compression
Added unified OfficeConverter interface for all document types
Enhanced metadata extraction for all formats
Improvements:
Smart caching system with hash-based file identification
Lazy-loading of format-specific converters for better performance
Better error handling and validation
Comprehensive test suite for all formats
Tools:
Added get_supported_formats tool
Enhanced get_document_metadata for all formats
Improved list_conversions with detailed cache information
Initial release
Word document (.docx, .doc) conversion
Basic image extraction
MCP server implementation
Contributions are welcome! Here's how you can help:
Report Bugs: Open an issue with details and steps to reproduce
Suggest Features: Describe your idea and use case
Submit Pull Requests:
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request
# Clone and install with dev dependencies
git clone https://github.com/Asunainlove/office-reader-mcp.git
cd office-reader-mcp
pip install -e ".[dev]"
# Run tests
python test/test_all_formats.py
# Run linting (if configured)
black src/
ruff check src/MIT License - see LICENSE file for details.
Asunainlove
GitHub: @Asunainlove
Repository: office-reader-mcp
Issues: Report a bug
This project uses the following open-source libraries:
Model Context Protocol (MCP) by Anthropic
python-docx for Word processing
openpyxl for Excel processing
python-pptx for PowerPoint processing
Pillow for image processing
If you find this project helpful, please:
⭐ Star the repository
🐛 Report bugs and issues
💡 Suggest new features
🔀 Contribute code improvements
Happy converting! 🚀
Clear all cached conversions.
Removes all converted markdown files and extracted images from the cache. Use this to free up disk space or reset the conversion cache.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 effectively communicates that this is a destructive operation ('Removes all'), specifies what gets cleared ('converted markdown files and extracted images'), and implies it affects disk space. It lacks details on permissions, rate limits, or confirmation prompts, but covers core behavioral traits adequately for a zero-parameter tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action in the first sentence, followed by elaboration and usage context. Each sentence adds value: the first defines the tool, the second details what is removed, and the third provides usage scenarios. There is no wasted text, making it highly efficient.
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 simplicity (0 parameters, no output schema, no annotations), the description is nearly complete. It explains what the tool does, what it affects, and when to use it. The only minor gap is the lack of information on potential side effects, such as whether clearing the cache impacts ongoing conversions or requires specific permissions.
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 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, focusing instead on the tool's purpose and effects. A baseline of 4 is applied as it avoids unnecessary parameter details.
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 ('Clear all cached conversions') and resource ('converted markdown files and extracted images from the cache'), distinguishing it from sibling tools like list_conversions or read_converted_markdown which involve reading rather than clearing. The verb 'removes' reinforces the destructive nature of the operation.
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 guidance on when to use this tool ('to free up disk space or reset the conversion cache'), giving practical context. However, it does not specify when NOT to use it or mention alternatives, such as whether partial cache clearing is possible through other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert Office documents to Markdown format for Claude to read.
Supported formats:
Word: .docx, .doc
Excel: .xlsx, .xls (converts each sheet to a Markdown table)
PowerPoint: .pptx, .ppt (extracts text and images from slides)
Features:
Text extraction with formatting (headings, bold, italic, lists, tables)
Image extraction and optimization (auto-compressed for efficiency)
Speaker notes extraction from PowerPoint
Multi-sheet support for Excel
Images are automatically optimized (WebP format, max 1920x1080) to reduce size while maintaining readability for Claude.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the Office document. Supported: .docx, .doc, .xlsx, .xls, .pptx, .ppt | |
| extract_images | No | Whether to extract and include images (default: true) | |
| image_format | No | How to handle images: 'file' saves to disk (recommended), 'base64' embeds in markdown, 'both' does both | file |
| output_name | No | Custom name for the output (without extension). If not provided, generates from filename. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by detailing behavioral traits: text extraction with formatting, image extraction and optimization (WebP format, max 1920x1080), speaker notes extraction, and multi-sheet support. It covers key aspects like output format (Markdown) and efficiency features, though it doesn't mention error handling or performance limits.
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 sections for supported formats and features, and each sentence adds useful information. It could be slightly more concise by integrating the image optimization detail into the features list, but overall it's front-loaded and efficient with minimal waste.
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 no annotations and no output schema, the description does a good job covering the tool's behavior, supported formats, and features. It provides enough context for an agent to understand what the tool does and how to use it, though it doesn't specify return values or error cases, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds some value by listing supported formats and image optimization details, but does not provide additional semantic context for parameters beyond what's in the schema (e.g., it doesn't explain implications of image_format choices or output_name usage).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: converting Office documents to Markdown format for Claude to read. It specifies the exact formats supported (Word, Excel, PowerPoint with file extensions) and distinguishes it from siblings like get_document_metadata or read_converted_markdown by focusing on conversion rather than metadata retrieval or reading.
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 stating it's for Claude to read and listing supported formats, but does not explicitly state when to use this tool versus alternatives like get_supported_formats or list_conversions. It provides clear input requirements but lacks explicit guidance on tool selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata from an Office document without full conversion.
Extracts document properties like title, author, creation date, etc. Faster than full conversion when you only need metadata.
Supported formats: .docx, .doc, .xlsx, .xls, .pptx, .ppt
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the Office document. Supported: .docx, .doc, .xlsx, .xls, .pptx, .ppt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's a read operation (implied by 'Get', 'Extracts'), it's faster than full conversion, and it supports specific formats. However, it lacks details on error handling, performance limits, or what metadata fields are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by supporting details in three concise sentences. Each sentence adds value: the first states what it does and doesn't do, the second lists extracted properties, the third explains performance benefit, and the fourth specifies formats. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (single parameter, no output schema, no annotations), the description is largely complete: it covers purpose, usage, performance, and formats. However, it doesn't specify the exact metadata fields returned (e.g., 'title, author, creation date, etc.' is vague), which could be improved since there's no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the baseline is 3. The description adds value by reiterating supported formats in the parameter context, reinforcing constraints. However, it doesn't provide additional semantic details beyond what's in the schema (e.g., file path examples or format validation rules).
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 ('Get metadata', 'Extracts document properties') and resource ('Office document'), distinguishing it from siblings like convert_document (full conversion) and read_converted_markdown (content extraction). It explicitly mentions what it does not do ('without full conversion').
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 guidance on when to use this tool ('Faster than full conversion when you only need metadata') and when to use alternatives (implied: use convert_document for full conversion). It also lists supported formats, helping users avoid unsupported files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get list of all supported file formats.
Returns a dictionary of file types (word, excel, powerpoint) and their extensions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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. While it mentions the return format ('dictionary of file types... and their extensions'), it doesn't address important behavioral aspects like whether this is a cached operation (relevant given the 'clear_cache' sibling), whether it requires authentication, rate limits, or error conditions. The description provides basic output information but lacks comprehensive behavioral context.
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 perfectly concise and well-structured. The first sentence states the core purpose, and the second sentence provides essential output details. Every sentence earns its place with no wasted words, and the information is front-loaded appropriately for quick understanding.
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 simplicity (no parameters, no output schema, no annotations), the description is reasonably complete for a basic lookup tool. It explains what the tool does and what it returns. However, without annotations or output schema, it could benefit from more detail about the return structure (e.g., format of the dictionary, whether it includes MIME types) and behavioral context about caching or performance characteristics.
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 tool has zero parameters (schema coverage 100%), so there are no parameters to document. The description appropriately doesn't waste space discussing nonexistent parameters. According to the scoring rules, zero parameters warrants a baseline score of 4, as there's nothing to compensate for and no unnecessary parameter discussion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get list of all supported file formats.' This specifies the verb ('Get') and resource ('supported file formats'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_conversions' or 'get_document_metadata', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'list_conversions' and 'get_document_metadata' available, there's no indication of when this specific tool is appropriate versus those other options. The description simply states what it does without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all cached document conversions.
Shows all documents that have been converted, including their output paths and number of extracted images. Useful for finding previously converted files.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool shows 'cached' conversions and lists specific output details, but doesn't address important behavioral aspects like whether results are paginated, sorted, or limited; whether it requires specific permissions; or what happens if the cache is empty. The description provides some context but leaves significant gaps.
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 perfectly concise and well-structured: three sentences with zero waste. The first sentence states the core purpose, the second elaborates on what's included, and the third provides usage context. Every sentence earns its place and information is front-loaded.
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 no annotations, no output schema, and 0 parameters, the description provides adequate basic information about what the tool does and when to use it. However, for a tool that presumably returns potentially complex conversion data, the description doesn't explain the return format, structure, or limitations. It's minimally viable but lacks details about what the agent should expect as output.
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 tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and instead focuses on what the tool returns, which is valuable context for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all cached document conversions' with specific details about what information is included (output paths and number of extracted images). It distinguishes from siblings by focusing on cached conversions rather than conversion operations or metadata retrieval, though it doesn't explicitly name alternatives.
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 implied usage guidance: 'Useful for finding previously converted files' suggests this tool should be used when looking for conversion history rather than performing new conversions. However, it doesn't explicitly state when NOT to use it or name specific alternative tools like 'read_converted_markdown' for accessing converted content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the content of a previously converted markdown file.
Use this after convert_document to get the actual markdown content. This is useful when you want to process or analyze the converted document.
| Name | Required | Description | Default |
|---|---|---|---|
| markdown_path | Yes | Path to the markdown file (returned by convert_document) |
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 describes the tool's behavior as reading content from a file, which is straightforward. However, it doesn't disclose potential behavioral traits like error handling (e.g., if the file doesn't exist), performance considerations, or output format details. The description adds some context but lacks depth for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with three sentences that each serve a clear purpose: stating the tool's function, providing usage guidelines, and explaining its utility. There is no wasted text, and it's front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no output schema, no annotations), the description is adequate but has gaps. It explains the purpose and usage well but lacks details on behavioral aspects like error handling or output format. For a read operation with no structured output information, more context on what 'content' entails would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with 'markdown_path' clearly documented as 'Path to the markdown file (returned by convert_document).' The description adds minimal value beyond this, only implying the parameter's purpose through context. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Read the content of a previously converted markdown file.' It specifies the verb ('read') and resource ('converted markdown file'), making it easy to understand. However, it doesn't explicitly differentiate from siblings like 'get_document_metadata' or 'list_conversions' beyond mentioning 'convert_document'.
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 guidance on when to use this tool: 'Use this after convert_document to get the actual markdown content.' It also clarifies the context: 'This is useful when you want to process or analyze the converted document.' This clearly distinguishes it from alternatives and specifies prerequisites.
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.
v1.0.0clear_cacheconvert_documentget_document_metadataget_supported_formatslist_conversionsread_converted_markdownScored across 6 tools
Each tool has a clearly distinct purpose with no overlap: clear_cache manages cache, convert_document performs conversions, get_document_metadata extracts metadata, get_supported_formats lists formats, list_conversions shows cached items, and read_converted_markdown reads converted content. The descriptions reinforce these distinct roles, making misselection unlikely.
All tool names follow a consistent verb_noun pattern (e.g., clear_cache, convert_document, get_document_metadata, get_supported_formats, list_conversions, read_converted_markdown). This uniformity in naming makes the tool set predictable and easy to navigate for an agent.
With 6 tools, the count is well-scoped for the server's purpose of reading Office documents. Each tool serves a specific function in the conversion and caching workflow, from format support to content retrieval, without being excessive or insufficient for the domain.
The tool set provides complete coverage for the Office document reading domain: it supports conversion (convert_document), metadata retrieval (get_document_metadata), format listing (get_supported_formats), cache management (clear_cache, list_conversions), and content access (read_converted_markdown). There are no obvious gaps in the lifecycle from input to output.
Convert documents and web pages to clean Markdown: PDF, DOCX, XLSX, EPUB, scanned files, any URL.
PDF, Word, PowerPoint, Excel, HTML, EPUB to Markdown: OCR, page ranges, tables, RAG chunking
Parse PDF/Word/PPT/HTML to Markdown; tables as JSON, image extraction, RAG chunking, page ranges.
Convert PDF, DOCX, HTML, and URLs to clean, LLM-ready markdown with tables preserved
