Skip to main content
Glama
KitchenSink4AI

io.github.nometalalchemist/kitchensink4xl

by KitchenSink4AI
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

query_range

Read-only

Filter, project, sort, paginate, and aggregate spreadsheet ranges server-side, so agents read only the rows and columns they need instead of an entire sheet.

Instructions

Filter, project, sort, paginate, and aggregate a range SERVER-SIDE so an agent reads only the rows and columns it needs instead of a whole sheet.

location defaults to the sheet's true used range. With header=true the first row names the columns (otherwise the A1 letter does). where is a list of {column, op, value} predicates joined by match ('all' or 'any'); ops: eq, ne, gt, ge, lt, le, contains, startswith, endswith, regex, in, not_in, is_blank, not_blank. columns projects a subset; order_by is a list of {column, dir} specs (unknown directions refuse); offset and limit page; distinct dedupes. aggregate is a list of {column, func} (count, count_nonblank, count_distinct, sum, avg, min, max, first, last), optionally per group_by (records=true emits objects).

Semantics: predicates read CACHED and literal values (uncalculated formulas read as blank; recalc for exact results); gt/ge/lt/le compare numerically when both sides coerce, else case-folded text; blanks never satisfy ordered comparisons; regex is timeout-guarded. Aggregates follow Excel: sum/avg/min/max consume NUMERIC cells only (text and booleans ignored even when text looks numeric; exclusions are reported); count is the RAW row count, unlike Excel COUNT; min/max fall back to text when no numbers exist. Filter-hidden rows are read and aggregated like any other row, unlike SUBTOTAL; use where to drop them. Read-only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYes
limitNo
matchNoall
sheetNo
whereNoFilter predicates, {column, op, value}, joined by match.
headerNo
offsetNo
valuesNocached
columnsNoColumns to project: header names, letters, or 1-based numbers.
recordsNo
distinctNo
group_byNoOne column to group by, or several.
locationNo
order_byNoSort specs, {column, dir}; unknown directions refuse.
aggregateNoAggregations, {column, func}, optionally per group_by.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.0
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "type": "object"
-}New value: +null
  2. Changed13 schema fields changedv1.1.0
    • changedInput schema / properties / aggregate / anyOf
      Previous value: -[
-  {
-    "items": {},
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "column": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "minimum": 1,
+              "type": "integer"
+            }
+          ],
+          "description": "A column: a header name, a column letter, or a 1-based number."
+        },
+        "func": {
+          "enum": [
+            "count",
+            "count_nonblank",
+            "count_distinct",
+            "sum",
+            "avg",
+            "min",
+            "max",
+            "first",
+            "last"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "column",
+        "func"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / aggregate / description
      Added value: +"Aggregations, {column, func}, optionally per group_by."
    • changedInput schema / properties / columns / anyOf
      Previous value: -[
-  {
-    "items": {},
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "minimum": 1,
+          "type": "integer"
+        }
+      ]
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / columns / description
      Added value: +"Columns to project: header names, letters, or 1-based numbers."
    • addedInput schema / properties / group_by / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "minimum": 1,
+    "type": "integer"
+  },
+  {
+    "items": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "minimum": 1,
+          "type": "integer"
+        }
+      ],
+      "description": "A column: a header name, a column letter, or a 1-based number."
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / group_by / description
      Added value: +"One column to group by, or several."
    • removedInput schema / properties / group_by / title
      Removed value: -"Group By"
    • addedInput schema / properties / location / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
    • removedInput schema / properties / location / title
      Removed value: -"Location"
    • changedInput schema / properties / order_by / anyOf
      Previous value: -[
-  {
-    "items": {},
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "column": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "minimum": 1,
+              "type": "integer"
+            }
+          ],
+          "description": "A column: a header name, a column letter, or a 1-based number."
+        },
+        "dir": {
+          "enum": [
+            "asc",
+            "desc"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "column"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / order_by / description
      Added value: +"Sort specs, {column, dir}; unknown directions refuse."
    • changedInput schema / properties / where / anyOf
      Previous value: -[
-  {
-    "items": {},
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "column": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "minimum": 1,
+              "type": "integer"
+            }
+          ],
+          "description": "A column: a header name, a column letter, or a 1-based number."
+        },
+        "op": {
+          "enum": [
+            "eq",
+            "ne",
+            "gt",
+            "ge",
+            "lt",
+            "le",
+            "contains",
+            "startswith",
+            "endswith",
+            "regex",
+            "in",
+            "not_in",
+            "is_blank",
+            "not_blank"
+          ],
+          "type": "string"
+        },
+        "value": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            },
+            {
+              "items": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              },
+              "type": "array"
+            }
+          ],
+          "description": "the value to compare against; type follows the column"
+        }
+      },
+      "required": [
+        "column",
+        "op"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / where / description
      Added value: +"Filter predicates, {column, op, value}, joined by match."
  3. First observedv1.0.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses cached-value reads, formula handling, comparison coercion rules, regex timeout guarding, Excel-compatible aggregate semantics, and treatment of hidden rows. This is substantial behavioral context that annotations alone do not provide.

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 long but organized into purpose, parameter tour, and semantics sections, with the core value proposition front-loaded. Some enum lists duplicate the schema, but they are presented compactly and are useful in prose; the density justifies the length.

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?

For a 15-parameter query tool with no output schema, the description covers operations, edge cases, and behavioral semantics thoroughly. The main gap is the default return shape—it only states records=true emits objects—so an agent must infer the non-records response format.

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 only 33%, but the description compensates by explaining the where predicate shape and ops, column references, columns projection, order_by behavior, offset/limit, distinct, aggregate functions, group_by, records, and location/header defaults. It maps nearly every parameter to semantics 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 opening sentence names a specific verb set—filter, project, sort, paginate, and aggregate—attached to a range, and frames it as server-side subsetting so an agent avoids reading a whole sheet. This clearly distinguishes it from siblings like read_range and get_table.

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 clearly establishes the use case: when an agent needs only the rows and columns it needs rather than the whole sheet. It does not name alternative tools or explicit when-not-to-use conditions, so it misses the top tier, but the context is clear enough for tool selection.

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

Install Server

Other Tools