xlsx-tools-mcp

Overview Schema Source Related Servers Discussions Admin

read_sheet

Read cell values from an Excel sheet as arrays, records, or markdown tables. Limit rows, offset, or select a range to extract only the data you need from large spreadsheets.

Instructions

Read cell values from a sheet.

Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. cell_range: Optional A1-style range (e.g. "B2:F20"). Omit to read the full used area. max_rows: Optional cap on the number of rows returned, to bound response size for large sheets. offset_row: Skip a number of data rows (0-indexed from first data row). format: "array" (default 2D list), "records" (list of dicts, first row as keys), or "markdown" (table string).

Input Schema

TableJSON Schema

Name	Required	Default
`path`	No
`sheet`	Yes
`format`	No	array
`max_rows`	No
`cell_range`	No
`offset_row`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.3.0Oct 4, 2026

addedInput schema / properties / format

Added value: +{
+  "default": "array",
+  "title": "Format",
+  "type": "string"
+}

addedInput schema / properties / offset_row

Added value: +{
+  "default": 0,
+  "title": "Offset Row",
+  "type": "integer"
+}

First observedv0.1.0Aug 17, 2026

TDQS

A4.2/5.0

Behavior4/5

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

No annotations, so the description must carry the behavioral load. It discloses several traits: default format is 'array', max_rows bounds response size, offset_row skips data rows (0-indexed), and cell_range can be omitted for full area. While it doesn't disclaim side effects (implied read-only by verb), this is significant context beyond the schema.

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 a clear first sentence stating purpose, followed by a bullet-like Args section. No wasted words; front-loaded purpose statement.

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?

An output schema exists, so return value explanation is not needed. The description covers all parameters and their semantics, making the tool invocation clear. It could add a note about error conditions or sibling relationships, but for a 6-parameter read tool with full param disclosure, it is largely complete.

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%. The description compensates well: it explains path ('.xlsx file or preloaded file name', and when it can be omitted), cell_range (A1-style example given), max_rows (purpose: 'bound response size'), offset_row (0-indexed from first data row), and format enum options with their meanings. This is substantial added meaning beyond bare property names.

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?

Specific verb+resource: 'Read cell values from a sheet'. Clearly distinguishes from siblings like get_cell (single-cell read), query_sheet (filtering), aggregate_sheet (computation) by describing a range/full-sheet read.

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?

No explicit when-to-use guidance or comparison to siblings. The parameter descriptions (e.g., 'Omit to read full used area') imply usage scenarios but do not proactively route the agent, such as telling it to use get_cell for a single cell or query_sheet for filtering.

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