What can you do with this server?

The excel-vision-mcp server enables AI agents to comprehensively analyze Excel workbooks by extracting both text data and embedded images, entirely on your local machine. * List Sheets (list_sheets): View all sheets in a workbook, including dimensions, merged cell counts, and total image counts. * Read Cell Data (read_excel_data): Extract cell values from a specific sheet with pagination support (start_row + max_rows), returning structured data with coordinate labels and merged cell indicators. * Extract Images (extract_images): Pull all embedded images as base64-encoded ImageContent with cell-position metadata and optional resizing — enabling vision-capable AI models to analyze them directly. * Read Full Content (read_full_content): The all-in-one tool — retrieves every sheet's text data and all embedded images in a single call, ideal for comprehensive analysis of reports, requirement docs, or design specs. * Get Workbook Overview (get_workbook_overview): Quickly retrieve file metadata, sheet list, dimensions, image count, and merged cell info for a fast structural assessment. * Search Across Cells (search_excel): Perform case-insensitive text searches across all cells in a workbook, returning matching coordinates and values. Key highlights: Supports .xlsx and .xlsm formats; handles large files via pagination; dual image extraction (cell-position mapping + ZIP archive fallback); all processing is 100% local.

How do I use excel-vision-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@excel-vision-mcp extract all images from financial report.xlsx" 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.

excel-vision-mcp

by VOYAGER-Inc

Overview Schema Source Related Servers Discussions Admin

Python

Local

📊 Excel Vision MCP

Your AI reads the spreadsheet. It can't see the diagram in cell B12.

This fixes that. Other Excel MCP servers return cell values and silently drop every embedded image, so the flowchart your spec depends on never reaches the model. Excel Vision MCP returns them as native ImageContent your AI can actually look at — alongside the text, formatting, and formulas.

Python 3.11+ License: MIT MCP PyPI

Installation · Tools · Configuration · How It Works · FAQ

🤔 The Problem

Ask your assistant to review a requirements spec. Half the meaning lives in screenshots, flowcharts, and annotated diagrams pasted into cells — and every Excel MCP server hands the model text only. The answer comes back confident and incomplete, because the model never knew the pictures existed.

The same blind spot applies to the other signals authors leave behind:

What the author did	What other MCP servers report	What Excel Vision MCP reports
Pasted a flowchart in `B12`	nothing	The image itself, mapped to `B12`
Struck through a cancelled row	`Legacy export`	`Legacy export [S]` — strikethrough
Highlighted a row for review	`Pending`	`Pending [HL:yellow]`
Hid an internal-cost column	The hidden values, as if normal	Skipped — unless a formula needs it

Same file. One agent sees a table of strings; the other sees what the author actually meant.

Related MCP server: Excel MCP Server

✨ Key Features

Feature	Description
🖼️ Image Extraction	Extracts all embedded images with cell-position mapping
📄 Full Content Reading	Text + images in a single call — nothing is missed
🏷️ Format-Aware Reading	Reports bold, strikethrough, highlights and font colors so agents read intent, not just text
🙈 Hidden-Content Aware	Skips hidden rows/columns by default, keeping those formulas depend on
✍️ Write Support	Create workbooks, update cells, write formulas, insert images
🎨 Formatting	Colors, fonts, borders, alignment, number formats, auto-fit columns
🛡️ Atomic Saves	A failed write can never corrupt your original file
📊 Smart Pagination	Handles massive spreadsheets without blowing up context
🔍 Text Search	Find content across all sheets instantly
🔒 100% Local	Your files never leave your machine
⚡ Fast	16MB file with 40 images processed in ~4 seconds
🖥️ Cross-Platform	macOS, Linux, Windows

Image Extraction — What Makes This Different

Most Excel MCP servers only read cell values. This server uses a dual extraction strategy:

Cell-Position Mapping (primary) — Maps each image to its exact cell location using openpyxl-image-loader
Archive Scanning (fallback) — Scans the xlsx ZIP archive's xl/media/ directory to catch any images missed by method 1

The result: zero images left behind, with position metadata when available.

👀 See It In Action

A requirements spec where the workflow lives in a pasted diagram and the status lives in cell colors:

You: Review this spec and tell me which features are still in scope, and how the dispatch flow works.

read_full_content returns the sheet as text with formatting markers, then the embedded diagram as an image:

Row 1: A1: Feature [B] [HL:blue] | B1: Status [B] [HL:blue]
Row 2: A2: Vehicle dispatch  | B2: Approved [HL:green]
Row 3: A3: Legacy CSV export [S] | B3: Cancelled [S]
Row 4: A4: Driver roll call  | B4: Needs review [HL:yellow]

ℹ️ Skipped 3 hidden row(s) with content. Pass include_hidden=true to read them.

**[Image 1]** Sheet: `Spec` | Cell: `B12` | Original: 1180×840px
[the actual flowchart, as ImageContent]

The model can now answer both halves of the question: "Legacy CSV export is struck through and marked cancelled, so three features remain in scope — and the flowchart in B12 shows dispatch requires roll-call confirmation before assignment."

Without image support, the second half is unanswerable. Without formatting, the cancelled row looks identical to the active ones.

🚀 Quick Start

Install via `uvx` (Recommended)

No installation needed — runs directly:

uvx excel-vision-mcp

Install via `pip`

pip install excel-vision-mcp

Then run:

excel-vision-mcp

Install from source

git clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git
cd excel-vision-mcp
uv sync
uv run excel-vision-mcp

Run with Docker

docker build -t excel-vision-mcp .
docker run --rm -i -v /path/to/spreadsheets:/data excel-vision-mcp

The server speaks JSON-RPC over stdin/stdout, so it must run attached (-i). Mount the directory holding your files and reference them by their in-container path (/data/report.xlsx). The image sets EXCEL_VISION_MCP_ALLOWED_DIRS=/data, so reads and writes stay inside the mount.

As an MCP client config:

{
  "mcpServers": {
    "excel-reader": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/spreadsheets:/data", "excel-vision-mcp"]
    }
  }
}

🔧 Configuration

Add the server to your MCP client's configuration file.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Windsurf / VS Code (Copilot)

Edit your MCP settings file:

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Antigravity IDE

Edit ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Note: After editing the config, restart your IDE/client to load the new server.

Restricting file access (optional)

By default the server can read/write any Excel file your user account can access. To sandbox it to specific directories, set EXCEL_VISION_MCP_ALLOWED_DIRS (multiple paths separated by : on macOS/Linux, ; on Windows):

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"],
      "env": {
        "EXCEL_VISION_MCP_ALLOWED_DIRS": "/Users/me/Documents/spreadsheets:/Users/me/Projects/data"
      }
    }
  }
}

🛠️ Available Tools

`list_sheets`

List all sheets with dimensions, merged cell counts, and image totals. Use this first to understand a workbook's structure.

list_sheets(file_path="/path/to/file.xlsx")

Returns: Sheet names, row×column dimensions, data ranges, merged cell counts, total image count.

`read_excel_data`

Read cell data from a specific sheet with pagination support.

read_excel_data(
    file_path="/path/to/file.xlsx",
    sheet_name="Sheet1",      # optional, defaults to first sheet
    start_row=1,              # optional, 1-indexed
    max_rows=200,             # optional, default 200
    include_hidden=False      # optional, read hidden rows/columns too
)

Returns: Cell values organized by row with coordinate labels and markers for merged cells and formatting.

Row 1: A1: Feature [B] [HL:blue] | B1: Status [B] [HL:blue]
Row 3: A3: Legacy export [S] | B3: Cancelled [S]
Row 4: A4: Report | B4: Needs review [HL:yellow] | C4: Urgent [B] [C:red]

Marker	Meaning
`[M]`	Merged cell
`[B]` `[I]` `[S]`	Bold · Italic · Strikethrough
`[HL:color]`	Highlighted background (color named, e.g. `yellow`, `red`)
`[C:color]`	Font color
`[HIDDEN-REF]`	Hidden cell kept because a visible formula references it

Markers and a short legend appear only on sheets that actually use formatting, so plain sheets cost no extra context.

`extract_images`

Extract all embedded images from the workbook as base64 ImageContent.

extract_images(
    file_path="/path/to/file.xlsx",
    sheet_name="Overview",    # optional, None = all sheets
    max_width=1024,           # optional, resize limit
    max_height=1024           # optional, resize limit
)

Returns: List of ImageContent (base64) with metadata — cell position, sheet name, original dimensions.

`read_full_content` ⭐

The star tool. Reads ALL text data AND all embedded images in a single call. Ideal for comprehensive document analysis.

read_full_content(
    file_path="/path/to/file.xlsx",
    max_rows_per_sheet=500,   # optional
    max_image_width=1024,     # optional
    max_image_height=1024     # optional
)

Returns: Complete workbook contents — every sheet's data as structured text (with formatting markers), followed by every embedded image with cell-position mapping.

Example use case: "Analyze this requirements document and summarize all use cases, including the workflow diagrams."

Hidden rows & columns

All read tools skip hidden rows and columns by default — an author who hid them signalled they aren't part of the content to review.

One exception: a hidden cell that a visible formula references is still returned, marked [HIDDEN-REF], because its value drives results you can see. Skipped content is always reported so nothing disappears silently:

ℹ️ Skipped 2 hidden row(s) with content. 1 hidden cell(s) are shown anyway
   because visible formulas reference them. Pass include_hidden=true to read them.

Pass include_hidden=true to read_excel_data, read_full_content, or search_excel to read everything.

`get_workbook_overview`

Quick structural summary of a workbook — file size, sheet list, dimensions, image count.

get_workbook_overview(file_path="/path/to/file.xlsx")

`search_excel`

Case-insensitive text search across all cells in the workbook.

search_excel(
    file_path="/path/to/file.xlsx",
    query="revenue",
    sheet_name="Q4 Report"    # optional, None = all sheets
)

Returns: Matching cells with sheet name, coordinate, and value. Limited to 100 results.

`create_excel_file`

Create a new empty workbook with the sheets you name.

create_excel_file(
    file_path="/path/to/new.xlsx",
    sheet_names=["Summary", "Detail"],  # optional, default ["Sheet1"]
    overwrite=False                     # optional, refuses to replace by default
)

`add_excel_sheet`

Add a new empty sheet to an existing workbook.

add_excel_sheet(file_path="/path/to/file.xlsx", sheet_name="Q3", position=0)

`update_excel_cells`

Set individual cells by coordinate. Values starting with = are written as formulas.

update_excel_cells(
    file_path="/path/to/file.xlsx",
    updates={"A1": "Title", "B2": 42, "C2": "=SUM(B2:B10)"},
    sheet_name="Data"             # optional, defaults to first sheet
)

Note: newly written formulas show no calculated value until the file is opened in Excel. For merged ranges, write to the top-left anchor cell.

`write_excel_rows`

Write a rectangular block of tabular data in one call.

write_excel_rows(
    file_path="/path/to/file.xlsx",
    rows=[["Item", "Qty"], ["Widget", 4], ["Gadget", 7]],
    sheet_name="Data",            # optional
    start_cell="A1"               # optional
)

`insert_excel_image`

Insert a local image file into a workbook, anchored at a cell.

insert_excel_image(
    file_path="/path/to/file.xlsx",
    image_path="/path/to/chart.png",
    cell="B2",
    sheet_name="Report",          # optional
    width=480, height=320         # optional display size in px
)

`format_excel_cells`

Style a range: font, colors, borders, alignment, number formats. Only the attributes you pass are changed — existing styling is preserved.

format_excel_cells(
    file_path="/path/to/file.xlsx",
    cell_range="A1:D1",
    bold=True,
    font_color="FFFFFF",
    fill_color="4472C4",
    horizontal_align="center",
    border_style="thin",          # thin | medium | thick | double | dashed | dotted
    border_edges="all",           # "all" or "outline" (outer edge of range only)
    number_format="#,##0.00"      # any Excel format code
)

`set_excel_column_widths`

Set column widths manually and/or auto-fit to content.

set_excel_column_widths(
    file_path="/path/to/file.xlsx",
    widths={"A": 12, "B": 35},    # explicit widths (skipped by auto-fit)
    auto_fit=True,                # size remaining columns to content
    max_width=60,                 # cap for auto-fit
    wrap_overflow=True            # wrap cells longer than the cap
)

Auto-fit counts full-width CJK characters (日本語) as 2 units. Cells longer than max_width get wrap text enabled instead of stretching the column — Excel auto-expands their row heights on open.

All write tools use atomic saves: the workbook is written to a temp file and swapped into place, so a failed save never corrupts your original. .xlsm macros are preserved. Known openpyxl limitation: pivot tables and some complex chart features are not preserved on re-save.

⚙️ How It Works

Architecture

Your AI Client (Claude, Cursor, etc.)
       │
       │ stdio (JSON-RPC)
       ▼
┌─────────────────────────────┐
│     Excel Vision MCP        │
│                             │
│  ┌───────────────────────┐  │
│  │   openpyxl            │  │──→ Cell data, formulas, merged cells
│  │   (Excel parser)      │  │
│  └───────────────────────┘  │
│                             │
│  ┌───────────────────────┐  │
│  │ openpyxl-image-loader │  │──→ Images with cell positions
│  │ + zipfile (fallback)  │  │
│  └───────────────────────┘  │
│                             │
│  ┌───────────────────────┐  │
│  │   Pillow              │  │──→ Resize, optimize, base64 encode
│  │   (image processing)  │  │
│  └───────────────────────┘  │
└─────────────────────────────┘
       │
       │ TextContent + ImageContent
       ▼
  AI sees text AND images

Data Flow & Privacy

Your file stays on your machine. The server runs locally via stdio — no network requests, no uploads, no cloud.
Read tools never modify your files. All image processing happens in-memory (BytesIO buffers). Write tools change only the exact file you specify, via atomic saves (temp file + swap) that can never leave a half-written workbook.
Optional directory sandbox. Set EXCEL_VISION_MCP_ALLOWED_DIRS (path-separator-separated list) to restrict which directories the server may read or write. Unset = no restriction.
Memory is freed automatically. After each request, Python's garbage collector reclaims all buffers.

Image Processing Pipeline

Original image in .xlsx (e.g., 2048×1536px PNG)
  ↓ Extract from ZIP archive / drawing layer
  ↓ Resize to fit max dimensions (default 1024px)
  ↓ Compress (JPEG 80% / PNG optimized)
  ↓ Base64 encode
  → ImageContent returned to AI client (~100-300KB per image)

📋 Supported Formats

Format	Status	Notes
`.xlsx`	✅ Fully supported	Excel 2007+ Open XML
`.xlsm`	✅ Fully supported	Macro-enabled workbooks
`.xls`	❌ Not supported	Legacy Excel 97-2003 format
`.csv`	❌ Not supported	Use a CSV-specific tool

Image Types

Image Type	Cell-Mapped	Archive Extraction
PNG	✅	✅
JPEG	✅	✅
GIF	✅	✅
BMP	✅	✅
TIFF	⚠️ Partial	✅
EMF/WMF	❌	✅
`=IMAGE()` formula	❌	❌
Images in comments	❌	❌

📊 Performance

Tested on real-world enterprise Excel files (macOS, Apple Silicon):

File	Size	Sheets	Images Extracted	Time
Requirements Doc A	4.5 MB	12	24	2.4s
Requirements Doc B	5.0 MB	6	18	2.4s
Requirements Doc C	10.7 MB	6	13	1.5s
Master Spec	16.0 MB	12	40	4.4s

❓ FAQ

.xls is the legacy binary format (Excel 97-2003). It uses a completely different internal structure (BIFF) compared to .xlsx (ZIP-based Open XML). The libraries used (openpyxl, openpyxl-image-loader) only support the modern Open XML format. If you have .xls files, convert them to .xlsx using Excel or LibreOffice first.

The primary extraction method (openpyxl-image-loader) maps images to specific cells but may miss images that aren't anchored to the standard drawing layer. The fallback archive scanner catches these "orphan" images from the xl/media/ directory — you get every image, just without cell-position metadata for orphans.

Yes! Text data extraction works perfectly with any model. Image extraction will still return ImageContent, but text-only models will simply ignore the image data. You won't get errors.

Yes. The server runs entirely on your local machine via stdio transport. No data is sent over the network and no files are uploaded anywhere. Read tools never modify your files; write tools change only the file you explicitly target, using atomic saves so a failed write can't corrupt it. You can also sandbox the server to specific directories with the EXCEL_VISION_MCP_ALLOWED_DIRS environment variable.

The server uses read_only mode for data iteration and processes images in-memory one at a time. For extremely large files, use read_excel_data with pagination (start_row + max_rows) instead of read_full_content to control memory usage.

🗺️ Roadmap

Write support — Create workbooks, update cells, write formulas, insert images (v1.1.0)
Format-aware reading — Bold, strikethrough, highlights, colors; hidden-content handling (v1.2.0)
Formula evaluation — Show formulas alongside their calculated values
CSV/TSV support — Extend to other tabular formats
Conditional formatting — Extract formatting rules
Chart extraction — Render charts as images

🤝 Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

git clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git
cd excel-vision-mcp
uv sync
uv run pytest  # Run the test suite

📄 License

MIT — use it however you want.

Built for AI agents that need to see the whole picture, not just the text.

⭐ Star this repo if it helped you!

Available Tools

13 tools

add_excel_sheetA

Add a new empty sheet to an existing workbook.

@param file_path: Absolute path to the .xlsx/.xlsm file. @param sheet_name: Name for the new sheet; must not already exist. @param position: 0-based index to insert at. None = append at the end. @return: Confirmation with the updated sheet list.

ParametersJSON Schema

Name	Required	Description	Default
`position`	No
`file_path`	Yes
`sheet_name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior3/5

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

No annotations are provided, so the description must disclose behavioral traits. It explains that the tool adds an empty sheet, allows insertion at a position, and returns a confirmation. It does not mention potential side effects (e.g., file locking) or permissions needed, but for a simple additive operation, the behavior is adequately transparent.

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 concise, with a clear summary line followed by structured parameter documentation. Every sentence adds value, and no unnecessary information is present.

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 that an output schema exists and the tool is simple (3 parameters), the description covers the essential aspects: purpose, parameters, and return type. It could mention error handling (e.g., file not found, duplicate name), but the constraints are clear, making it reasonably complete.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the description compensates fully with detailed @param lines for all three parameters: file path absolute path, sheet name uniqueness constraint, and position with default behavior. This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Add a new empty sheet to an existing workbook.' It uses a specific verb and resource, and the sibling tools (e.g., list_sheets, create_excel_file) show distinction, making it unambiguous what this tool does.

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

Usage Guidelines4/5

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

The description implies when to use the tool (to add a sheet) and provides constraints (sheet_name must not exist, position can be None). However, it does not explicitly state when not to use it or recommend alternatives, such as when a sheet with that name already exists or for copying sheets.

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

create_excel_fileA

Create a new empty .xlsx workbook.

@param file_path: Absolute destination path; parent directory must exist. @param sheet_names: Sheet names to create in order. None = single "Sheet1". @param overwrite: Set true to replace an existing file. Default false. @return: Confirmation with the created sheet list.

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes
`overwrite`	No
`sheet_names`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries full transparency burden. It discloses key behaviors: file creation, overwrite control, sheet naming defaults, and the requirement for the parent directory to exist. It lacks details on error handling or atomicity but is otherwise solid.

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 concise with a clear opening sentence followed by bullet-like parameter descriptions. No extraneous information, and every sentence adds value.

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 three parameters and an existing output schema (though not shown), the description covers the necessary details for correct usage. It explains parameters, return value, and file path constraints. Minor gaps include no mention of error scenarios or non-destructive nature.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, requiring the description to explain all parameters. It does so effectively: file_path is absolute with directory requirement, sheet_names defaults to 'Sheet1', and overwrite defaults to false. This adds essential meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a new empty .xlsx workbook,' which is a specific verb and resource. It effectively distinguishes from sibling tools that read, modify, or add sheets, making selection straightforward.

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?

No guidance is provided on when to use this tool versus its siblings (e.g., add_excel_sheet for adding sheets to existing files). The description focuses only on parameters without advising on appropriate context.

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

extract_imagesA

Extract all embedded images from an Excel file.

Uses dual extraction strategy: cell-position mapping (primary) and ZIP archive scanning (fallback) to ensure no images are missed. Returns images as base64-encoded ImageContent that AI can visually analyze.

@param file_path: Absolute path to the .xlsx file. @param sheet_name: Specific sheet, or None for all sheets. @param max_width: Max width in pixels for image optimization (default 1024). @param max_height: Max height in pixels for image optimization (default 1024). @return: Mixed list of TextContent (metadata) and ImageContent (images).

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes
`max_width`	No
`max_height`	No
`sheet_name`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

No annotations present, so description carries full burden. Details dual extraction strategy, base64 encoding, and returns metadata+images. No contradictions.

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?

Concise, front-loaded with purpose, then strategy, then parameter details. Every sentence adds value without redundancy.

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?

With no annotations but an output schema, description covers extraction strategy, params, and return types. Could mention output schema structure more explicitly, but still complete.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, but description's @param lines explain all 4 parameters well (file_path as absolute path, sheet_name as optional, max_width/height defaults).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Extract all embedded images from an Excel file.' Specific verb+resource, and distinct from sibling tools that handle data/content.

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?

Describes extraction strategy and intended use (AI visual analysis), but lacks explicit when-not-to-use or comparisons to alternatives.

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

format_excel_cellsA

Apply formatting to a cell range: font, colors, borders, alignment, number format.

Only the attributes you pass are changed; existing styling is preserved. Example — style a header row: cell_range="A1:D1", bold=true, font_color="FFFFFF", fill_color="4472C4", horizontal_align="center", border_style="thin".

@param file_path: Absolute path to the .xlsx/.xlsm file. @param cell_range: Range like "A1:C10" or a single cell like "B2". @param sheet_name: Target sheet. None = first sheet. @param font_name: Font family (e.g. "Calibri"). @param font_size: Font size in points. @param bold: Bold on/off. @param italic: Italic on/off. @param font_color: Text color, RRGGBB hex (e.g. "FFFFFF"). @param fill_color: Background color, RRGGBB hex (e.g. "4472C4"). @param border_style: thin, medium, thick, double, dashed, or dotted. @param border_edges: "all" = every cell; "outline" = outer edge of range only. @param horizontal_align: left, center, right, or justify. @param vertical_align: top, center, or bottom. @param wrap_text: Enable/disable text wrapping. @param number_format: Excel format code (e.g. "#,##0.00", "dd/mm/yyyy", "0%"). @return: Confirmation with the number of cells formatted.

ParametersJSON Schema

Name	Required	Default
`bold`	No
`italic`	No
`file_path`	Yes
`font_name`	No
`font_size`	No
`wrap_text`	No
`cell_range`	Yes
`fill_color`	No
`font_color`	No
`sheet_name`	No
`border_edges`	No	all
`border_style`	No
`number_format`	No
`vertical_align`	No
`horizontal_align`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations provided, the description effectively covers behavioral traits: it specifies that formatting is selective (only changed attributes), and mentions the return value is a confirmation with cell count. It does not contradict any annotations.

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 well-structured with a brief introductory sentence, a usage example, and a clear @param listing for all 15 parameters. While slightly long, it earns its length given the tool's complexity, with no wasted sentences.

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 15 parameters and no existing annotations or output schema shown, the description covers all essential aspects: file path, cell range, formatting options, and return value (confirmation with cell count). It is complete for effective tool usage.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema description coverage is 0%, the description compensates by documenting each parameter with type, example values, and allowed options (e.g., 'thin, medium, thick, double, dashed, or dotted' for border_style). This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Apply formatting to a cell range' and lists specific formatting options (font, colors, borders, alignment, number format), making the purpose unambiguous. It distinguishes itself from sibling tools like update_excel_cells (which updates values) and set_excel_column_widths.

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 explains that only passed attributes are changed and existing styling is preserved, providing clear usage context. It includes an example of styling a header row. While it doesn't explicitly state when not to use, the sibling list implies alternatives for other operations.

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

get_workbook_overviewA

Get a quick summary overview of an Excel workbook.

Returns file metadata, sheet list with dimensions, image count, and merged cell information. Use this for a fast assessment before deeper analysis.

@param file_path: Absolute path to the .xlsx file. @return: Formatted text summary.

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It discloses what the tool returns (file metadata, sheet list, dimensions, image count, merged cells) and that it works with .xlsx files. No side effects mentioned, but for a read-only overview tool this is adequate.

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?

Four sentences, front-loaded with purpose, then details and usage guidance. No wasted words; every sentence adds value.

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

Completeness5/5

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

For a simple overview tool with one parameter, an existing output schema, and sibling tools, the description is complete. It lists return content and usage context, leaving no critical gaps.

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 single parameter file_path is described as 'Absolute path to the .xlsx file', adding format and path type information beyond the schema. Schema coverage is 0%, so description compensates well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns a quick summary overview of an Excel workbook, listing specific content (file metadata, sheet list, image count, merged cells). It distinguishes from deeper analysis tools by implying this is for fast assessment before deeper work.

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?

Explicitly says 'Use this for a fast assessment before deeper analysis', providing clear when-to-use context. Does not explicitly list when not to use or alternatives, but sibling tools are present for differentiation.

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

insert_excel_imageA

Insert an image from a local file into a workbook, anchored at a cell.

@param file_path: Absolute path to the .xlsx/.xlsm file. @param image_path: Absolute path to the image file (PNG/JPEG/GIF/BMP). @param cell: Anchor cell coordinate (e.g. "B2"). @param sheet_name: Target sheet. None = first sheet. @param width: Display width in pixels. None = natural size. @param height: Display height in pixels. None = natural size. @return: Confirmation with anchor position and display size.

ParametersJSON Schema

Name	Required	Description	Default
`cell`	Yes
`width`	No
`height`	No
`file_path`	Yes
`image_path`	Yes
`sheet_name`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/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 full burden. It mentions the action (insert) and output (confirmation with position and size), but does not disclose side effects (e.g., file modification, overwrite behavior) or requirements (e.g., file must not be open).

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 well-structured with a one-sentence summary and clear @param/@return blocks. It is appropriately sized for the tool's complexity, though it could be slightly more concise.

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?

The description covers all parameters, return value, and anchor behavior. Given that an output schema exists, return details are sufficient. It could mention edge cases or limitations (e.g., image size limits), but overall it is complete enough for effective use.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides full parameter documentation (@param tags) with format examples and defaults, compensating completely for the 0% schema description coverage. It adds meaning beyond the schema for all 6 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool inserts an image from a local file into a workbook, anchored at a cell. It uses a specific verb ('Insert') and resource ('image'), and distinguishes from sibling tools like extract_images or read_excel_data.

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

Usage Guidelines3/5

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

The description implies usage (inserting images) but does not explicitly state when to use this tool versus alternatives or provide exclusions. No guidance on prerequisites or conditions is given.

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

list_sheetsA

List all sheets in an Excel workbook with their dimensions and metadata.

Returns sheet names, row/column counts, data ranges, merged cell counts, and total embedded image count. Use this to understand the structure of an Excel file before reading its contents.

@param file_path: Absolute path to the .xlsx file. @return: Formatted text with workbook structure overview.

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

Without annotations, the description carries full burden. It lists what is returned: 'sheet names, row/column counts, data ranges, merged cell counts, and total embedded image count.' It doesn't discuss side effects or permissions, but as a read-only listing, this is sufficient. The behavior is transparent.

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 three sentences plus a parameter note, all front-loaded with the primary action. Every sentence adds value, no redundancy. It is concise and well-structured.

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 that there is an output schema (context indicates 'Has output schema: true'), the description doesn't need to fully detail return values but does summarize them. The tool is simple with one required param, and the description provides enough context for an agent to use it effectively. Minor gap: no mention of error conditions or file existence checks.

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

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must document parameters. It explicitly describes the only parameter 'file_path' as 'Absolute path to the .xlsx file.' This adds meaning beyond the schema's type and title. It could include examples but is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'List all sheets in an Excel workbook with their dimensions and metadata.' It specifies the resource (sheets in a workbook) and the verb (list). The description distinguishes from siblings like 'read_excel_data' by explicitly mentioning it's for understanding structure before reading content.

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 a clear usage guideline: 'Use this to understand the structure of an Excel file before reading its contents.' This implies when to use (before reading tools) but does not explicitly mention when not to use or list alternative tools. However, the context makes it helpful.

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

read_excel_dataA

Read cell data from an Excel sheet with pagination for large files.

Returns cell values organized by row with coordinate labels and formatting markers ([B]=bold, [S]=strikethrough, [HL:color]=highlight, [C:color]=font color) that reveal the author's emphasis and status marks.

Hidden rows/columns are skipped by default — the author hid them for a reason — except hidden cells that visible formulas depend on, which are kept and marked [HIDDEN-REF].

@param file_path: Absolute path to the .xlsx file. @param sheet_name: Sheet to read. None = first/active sheet. @param start_row: Starting row number (1-indexed). @param max_rows: Maximum rows to return (default 200). @param include_hidden: Set true to also read hidden rows/columns. @return: Formatted text table with cell values and formatting markers.

ParametersJSON Schema

Name	Required	Description	Default
`max_rows`	No
`file_path`	Yes
`start_row`	No
`sheet_name`	No
`include_hidden`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

The description explains hidden rows/columns are skipped by default and kept as [HIDDEN-REF] if depended on by visible formulas. It also explains formatting markers. However, with no annotations, it doesn't state that the tool is read-only or safe, nor does it cover exceptions like missing files.

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 concise and front-loaded with the main purpose. The @param list is clear, though could be slightly more integrated. No superfluous sentences.

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 output schema existence, return value details are not fully required, but the description lacks error handling for missing files or sheets. It adequately covers pagination and hidden cells but misses edge case behaviors.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The @param section in the description fully explains each parameter's meaning and default, compensating for the 0% schema coverage. For example, 'sheet_name: None = first/active sheet' and 'include_hidden: Set true to also read hidden rows/columns.'

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read cell data from an Excel sheet with pagination for large files,' specifying the action and resource. It distinguishes from sibling tools like 'read_full_content' (no pagination) and 'search_excel' (searching).

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

Usage Guidelines3/5

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

The description implies use for large files via pagination but does not explicitly state when to use this tool versus alternatives like 'read_full_content' for small files. No prerequisites or when-not-to-use guidance is provided, leaving some ambiguity.

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

read_full_contentA

Read the FULL content of an Excel file including all text data AND embedded images.

This is the primary tool for comprehensive document analysis. Returns all sheet data as structured text followed by all extracted images with their cell positions. Ideal for analyzing documents where both text and diagrams/screenshots are essential, such as requirement definitions, reports, or design specs.

For very large files, data is paginated per sheet. Image extraction uses dual strategy (cell-mapping + archive) for maximum coverage. Cell text carries formatting markers ([B]=bold, [S]=strikethrough, [HL:color]= highlight) so emphasis and status marks survive into the analysis.

Hidden rows/columns are skipped by default, except hidden cells that visible formulas depend on.

@param file_path: Absolute path to the .xlsx file. @param max_rows_per_sheet: Max rows to read per sheet (default 500). @param max_image_width: Max width for image optimization (default 1024). @param max_image_height: Max height for image optimization (default 1024). @param include_hidden: Set true to also read hidden rows/columns. @return: Mixed list of TextContent and ImageContent covering entire workbook.

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes
`include_hidden`	No
`max_image_width`	No
`max_image_height`	No
`max_rows_per_sheet`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

Discloses key behaviors: pagination per sheet, dual-strategy image extraction, formatting markers, and hidden row/column handling. No annotations provided, so description carries full burden and adds significant value.

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?

Well-structured with front-loaded purpose, usage context, behavioral details, and parameter documentation. Each sentence adds value, though slightly lengthy.

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

Completeness5/5

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

Covers purpose, usage, behaviors, parameters, and output format (TextContent/ImageContent) with an existing output schema. Complete for the tool's complexity.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully explains all parameters with defaults and usage details (e.g., 'Absolute path', 'Max rows to read per sheet'). Compensates completely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Read the FULL content of an Excel file including all text data AND embedded images'. Distinguishes from siblings like 'read_excel_data' and 'extract_images' by emphasizing comprehensiveness and combined text-image output.

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?

Explicitly describes ideal use cases (requirement definitions, reports, design specs) and notes pagination for large files. Lacks explicit when-not-to-use or alternatives, but strong context implies scope.

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

search_excelA

Search for text content across all cells in an Excel workbook.

Performs case-insensitive substring search and returns matching cells with their coordinates and values. Hidden rows/columns are excluded by default. Limited to 100 results.

@param file_path: Absolute path to the .xlsx file. @param query: Text to search for. @param sheet_name: Limit to specific sheet, or None for all sheets. @param include_hidden: Set true to also search hidden rows/columns. @return: Formatted text with search results.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`file_path`	Yes
`sheet_name`	No
`include_hidden`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It clearly explains search behavior (case-insensitive substring, coordinate+value returns), default exclusions (hidden rows/columns), and limits (100 results). Missing details on error handling or performance, but sufficient for safe invocation.

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 efficient: a one-sentence purpose followed by a bullet-like list of behavioral traits and parameter notes. Every sentence adds value. The @param lines are slightly redundant with the schema but provide necessary semantics, so not wasteful.

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?

The tool has a straightforward search operation with 4 parameters, all explained. The output schema exists and description mentions return format (formatted text with coordinates and values). For its complexity, the description is sufficiently complete. Minor gap: no mention of case sensitivity or substring behavior in parameter notes, but covered in the behavioral paragraph.

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?

Despite 0% schema description coverage, the JSDoc-style @param notes in the description add critical meaning: file_path requires an absolute path, query is text to search, sheet_name can limit to specific sheet or None, include_hidden defaults false. These details compensate for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Search for text content across all cells in an Excel workbook,' clearly stating the verb (Search), resource (cells in an Excel workbook), and scope (all cells). This distinguishes the tool from siblings like list_sheets or read_excel_data which have different purposes.

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

Usage Guidelines3/5

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

The description provides useful behavioral details (case-insensitive substring search, hidden rows/columns excluded by default, 100-result limit) but does not explicitly state when to use this tool versus alternatives like read_excel_data or write_excel_rows. The usage context is implied but not contrasted with siblings.

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

set_excel_column_widthsA

Set column widths manually and/or auto-fit them to content.

Auto-fit sizes each column to its longest content (full-width CJK characters count double), capped at max_width. Cells longer than the cap get wrap_text enabled so long descriptions wrap onto multiple lines instead of stretching the column; Excel auto-expands their row heights on open. Columns in widths are set exactly and skipped by auto-fit.

@param file_path: Absolute path to the .xlsx/.xlsm file. @param sheet_name: Target sheet. None = first sheet. @param widths: Explicit widths per column letter, e.g. {"A": 12, "B": 35}. @param auto_fit: Auto-size all other columns in the used range. @param max_width: Width cap for auto-fit in character units (default 60). @param wrap_overflow: Wrap cells longer than max_width (default true). @return: Confirmation listing each column and the width applied.

ParametersJSON Schema

Name	Required	Description	Default
`widths`	No
`auto_fit`	No
`file_path`	Yes
`max_width`	No
`sheet_name`	No
`wrap_overflow`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

No annotations provided, but description fully discloses behavioral traits: auto-fit cap, wrap_text for long content, CJK double counting, row height expansion, and return confirmation.

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

Conciseness5/5

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

Well-structured with high-level overview first, then parameter documentation. Every sentence adds value without verbosity.

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

Completeness5/5

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

Covers all key aspects despite no annotations: main functionality, parameter semantics, return value (confirmation). Output schema exists, so return format doesn't need elaboration.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description documents each parameter with meaning: file_path absolute, sheet_name target, widths per column letter, auto_fit scope, max_width cap, wrap_overflow behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool sets column widths manually and/or auto-fits them, using specific verbs and resource. Distinguishes from sibling tools like format_excel_cells.

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?

Explains when to use auto-fit vs explicit widths, and that explicit widths skip auto-fit. Does not explicitly state when not to use or compare to all siblings, but provides solid context.

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

update_excel_cellsA

Set individual cells by coordinate, e.g. {"A1": "Title", "B2": 42}.

String values starting with "=" are written as formulas (e.g. "=SUM(A1:A5)"). Note: newly written formulas have no calculated value until the file is opened in Excel. For cells inside a merged range, write to the range's top-left anchor cell.

The save is atomic — a failed write never corrupts the original file.

@param file_path: Absolute path to the .xlsx/.xlsm file. @param updates: Mapping of cell coordinate to value. @param sheet_name: Target sheet. None = first sheet. @return: Confirmation with the number of cells written.

ParametersJSON Schema

Name	Required	Description	Default
`updates`	Yes
`file_path`	Yes
`sheet_name`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

Discloses atomic saves, formula calculation delay, and merged range behavior. No annotations were provided, so the description carries the full burden and does so well.

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?

Well-structured with a clear opening, bullet-like notes, and param docs. A bit verbose but not excessively so.

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

Completeness5/5

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

Covers all necessary behaviors, parameter semantics, and includes an output schema mention. Complete for a tool of this complexity.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Describes all three parameters: file_path, updates (with example), and sheet_name (with default behavior). Schema coverage is 0%, so the description fully compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool sets individual cells by coordinate, with an example. It distinguishes from siblings like write_excel_rows and format_excel_cells by focusing on cell-by-cell updates.

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

Usage Guidelines4/5

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

Provides specific notes about formula behavior and merged ranges, which guide correct usage. However, it lacks explicit when-to-use vs alternatives, though the context is clear.

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

write_excel_rowsA

Write a rectangular block of rows starting at start_cell.

Efficient for tabular data: pass a list of rows, each a list of values. Existing cells in the target range are overwritten; cells outside it are untouched. The save is atomic.

@param file_path: Absolute path to the .xlsx/.xlsm file. @param rows: List of rows, each a list of cell values. @param sheet_name: Target sheet. None = first sheet. @param start_cell: Top-left coordinate of the block (default "A1"). @return: Confirmation with the written range.

ParametersJSON Schema

Name	Required	Default
`rows`	Yes
`file_path`	Yes
`sheet_name`	No
`start_cell`	No	A1

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It discloses that existing cells are overwritten, cells outside range are untouched, and the save is atomic. This provides key behavioral traits, though it could mention file existence or permission requirements.

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 concise and front-loaded with the main action. It includes parameter documentation in a structured way without unnecessary text. One extra sentence could be trimmed but overall efficient.

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 4 parameters and an output schema (mentioned but not shown), the description provides sufficient context for usage, including return value description. It covers overwrite behavior and atomicity. No major gaps.

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%, but the description includes docstrings for each parameter, adding meaning like 'Absolute path' for file_path and 'Top-left coordinate' for start_cell. It compensates well for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool writes a rectangular block of rows starting at a start cell. The verb 'Write' and resource 'rows' are specific, and it distinguishes from sibling tools like update_excel_cells by emphasizing batch writing of rows.

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

Usage Guidelines3/5

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

The description says 'Efficient for tabular data' implying when to use, but does not explicitly compare with alternatives like update_excel_cells or mention when not to use. There is no guidance on prerequisites or exclusions.

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.

10 tool updatesv1.2.1Jul 30, 2026
- Addedadd_excel_sheet
- Addedcreate_excel_file
- Addedformat_excel_cells
- Addedinsert_excel_image
- Changedread_excel_data1 field changed
  - addedInput schema / properties / include_hidden
```
Added value: +{
+  "default": false,
+  "title": "Include Hidden",
+  "type": "boolean"
+}
```
- Changedread_full_content1 field changed
  - addedInput schema / properties / include_hidden
```
Added value: +{
+  "default": false,
+  "title": "Include Hidden",
+  "type": "boolean"
+}
```
- Changedsearch_excel1 field changed
  - addedInput schema / properties / include_hidden
```
Added value: +{
+  "default": false,
+  "title": "Include Hidden",
+  "type": "boolean"
+}
```
- Addedset_excel_column_widths
- Addedupdate_excel_cells
- Addedwrite_excel_rows
6 tool updatesv1.0.3Jul 16, 2026
- First observedextract_images
- First observedget_workbook_overview
- First observedlist_sheets
- First observedread_excel_data
- First observedread_full_content
- First observedsearch_excel

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-07-30 10:25 across 13 tools

Disambiguation3/5

Tools like list_sheets and get_workbook_overview have overlapping purposes, both providing workbook structure. Similarly, read_excel_data and read_full_content both read cell data, differing mainly in image inclusion and pagination. However, most other tools target distinct actions (e.g., search, image extraction, formatting), so disambiguation is adequate but not perfect.

Naming Consistency4/5

All tool names use snake_case and follow a verb_noun pattern (e.g., list_sheets, update_excel_cells, set_excel_column_widths). Minor variations in adjective placement (e.g., 'excel' vs 'workbook') are predictable and do not hinder recognition.

Tool Count5/5

With 13 tools, the server covers reading (structure, data, images, search) and writing (create, add sheet, update cells/rows, insert image, format, column widths) comprehensively without overwhelming excess.

Completeness3/5

Core read and write operations are well-covered, but notable gaps exist for deletion (no delete sheet, delete rows, or delete images). Renaming sheets and advanced formula handling are also missing, limiting full lifecycle management.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

excel-spreadsheet-xlsx-csv A
io.github.theluckystrike
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
Workplace & Productivity File Systems
131
Frenchie A
io.github.Lab94
OCR, transcription, file extraction, and image generation for AI agents via MCP.
AI & Machine Learning Image & Video Processing Speech Processing
72
Quadratic A
io.github.quadratichq
AI access to Quadratic spreadsheets: open files, run Python/SQL, query connected databases.
Data Platforms Databases Code Execution
52
Sheet Best MCP
io.github.sheetbest
Connect AI assistants to Google Sheets through controlled tools for reading and updating rows.
Workplace & Productivity App Automation
1

Related MCP Servers

MCP Local File Reader
File Systems Developer Tools
sworddut
A
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server that allows AI models to safely access and interact with local file systems, enabling reading file contents, listing directories, and retrieving file metadata.
Updated 2 years ago (2025-03-19 08:30 UTC)
6 npm
10
MIT
Excel MCP Server
Developer Tools File Systems Workplace & Productivity
alexhuangc
A
license
Not graded
quality
D
maintenance
Enables AI agents to create, read, and manipulate Excel files without requiring Microsoft Excel installation. Supports comprehensive spreadsheet operations including formulas, formatting, charts, pivot tables, and data validation.
Updated a year ago (2025-08-11 07:35 UTC)
MIT
Browserbase MCP Server
Browser Automation Web Scraping App Automation
AI-Zebra
A
license
A
quality
D
maintenance
Enables cloud browser automation through Browserbase and Stagehand, allowing LLMs to interact with web pages, take screenshots, extract data, and perform automated actions with support for proxies, stealth mode, and parallel sessions.
Updated a year ago (2025-07-28 00:51 UTC)
14
2,459 npm
Apache 2.0
Excel MCP Server
File Systems Workplace & Productivity Developer Tools
BACH-AI-Tools
A
license
Not graded
quality
D
maintenance
Enables AI agents to create, read, and modify Excel workbooks without requiring Microsoft Excel, supporting operations like formulas, charts, pivot tables, formatting, and data validation.
Updated 10 months ago (2025-12-04 05:37 UTC)
MIT

📊 Excel Vision MCP

Your AI reads the spreadsheet. It can't see the diagram in cell B12.

🤔 The Problem

✨ Key Features

Image Extraction — What Makes This Different

👀 See It In Action

🚀 Quick Start

Install via uvx (Recommended)

Install via pip

Install from source

Run with Docker

🔧 Configuration

Claude Desktop

Cursor

Windsurf / VS Code (Copilot)

Antigravity IDE

Restricting file access (optional)

🛠️ Available Tools

list_sheets

read_excel_data

extract_images

read_full_content ⭐

Hidden rows & columns

get_workbook_overview

search_excel

create_excel_file

add_excel_sheet

update_excel_cells

write_excel_rows

insert_excel_image

format_excel_cells

set_excel_column_widths

⚙️ How It Works

Architecture

Data Flow & Privacy

Image Processing Pipeline

📋 Supported Formats

Image Types

📊 Performance

❓ FAQ

🗺️ Roadmap

🤝 Contributing

📄 License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Install via `uvx` (Recommended)

Install via `pip`

`list_sheets`

`read_excel_data`

`extract_images`

`read_full_content` ⭐

`get_workbook_overview`

`search_excel`

`create_excel_file`

`add_excel_sheet`

`update_excel_cells`

`write_excel_rows`

`insert_excel_image`

`format_excel_cells`

`set_excel_column_widths`