Skip to main content
Glama
theluckystrike

mcp-office-suite

by theluckystrike
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

Filter, group and sort rows

sheet_query

Query and filter .xlsx or .csv files in one call: filter rows, group, aggregate (sum, count, avg, min, max) and sort without hand-computing totals over read rows.

Instructions

Call this tool for any spreadsheet or CSV file path; built-in file readers cannot parse spreadsheets and must not be used for them. Filter, group, aggregate and sort in one call; never hand sums over sheet_read rows.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
asNo
pathYesPath to the .xlsx or .csv file
sortNoSort column; may be an aggregate alias such as total_units
limitNoDefault 100
sheetNo
whereNoFilter, e.g. [Qty] >= 5 AND ([Status] = "open" OR [Status] = "new")
selectNoColumn names to return; default all (with group_by, defaults to the group columns plus the aggregates)
group_byNoGroup rows by these columns before aggregating, e.g. ["Rep"] or ["Region","Rep"]
aggregateNoAggregates per group, e.g. [{"col":"Units","fn":"sum","as":"total_units"}]. Defaults to a row count when group_by is given.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.20.0

TDQS

A4.1/5.0
Behavior3/5

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

Annotations are present but sparse, and the description adds workflow-level behavior (everything in one call, no need to read rows and aggregate manually). However it says nothing about side effects, output size/pagination beyond the schema's limit default, or cost, and it does not resolve the surprising readOnlyHint=false/idempotentHint=false flags for what is functionally a query operation.

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?

Two sentences, zero filler. The first sentence is front-loaded with the routing instruction (when to use this tool and which tools to avoid), and the second packs the operation set plus a do-not-workaround rule. Every clause earns its place.

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?

With 9 parameters including nested objects and no output schema, the description covers selection/routing well but is silent on return shape, pagination behavior at the 100-row default, and error/edge cases (missing sheet, bad column). Given the annotations carry some safety signal, it is adequate but not complete for a parameter-heavy tool.

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

Parameters3/5

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

Schema description coverage is 78% and the schema already carries rich per-parameter detail (where-clause syntax example, group_by examples, aggregate alias semantics, limit default). The description restates the capabilities at a high level but adds no syntax or interaction detail (e.g. how select interacts with group_by) beyond what the schema provides, so the baseline 3 applies.

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 names a concrete capability set — filter, group, aggregate, sort — over a concrete resource (any spreadsheet or CSV file path), and the title reinforces the row-level scope. It also implicitly separates itself from the generic row reader via 'never hand sums over sheet_read rows', so an agent can identify the right tool without opening schemas.

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

Usage Guidelines5/5

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

It gives explicit positive and negative routing: call this for any spreadsheet/CSV path, do NOT use the built-in file readers because they cannot parse spreadsheets, and do the aggregation here rather than summing sheet_read rows. Both the when-to-use and the when-not-to-use cases are stated with the alternative named.

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

Deploy Server

Other Tools