Skip to main content
Glama
KitchenSink4AI

io.github.nometalalchemist/kitchensink4xl

by KitchenSink4AI
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

sort_range

Sorts a spreadsheet range or table by one or more column keys, reordering rows while keeping headers and filter-hidden rows pinned. Supports ascending/descending order, tie-breaking, and preserves formulas with Excel-compatible behavior.

Instructions

Sort a range or table body by one or more keys, writing the rows back reordered. keys is a list of {column, order}: header name, letter, or 1-based index; asc or desc; later keys break ties. has_header keeps the first row put. Moved formulas shift relative refs (Excel semantics); keys compare cached values, warning when uncalculated. Filter-hidden rows stay pinned and unsorted, as in Excel. Hazardous workbooks need allow_loss. Auto-backup (prev is the undo); atomic verified save. Refuses while open in Excel.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
keysYesSort keys, {column, order}; later keys break ties.
pathYes
sheetNo
backupNo
locationYes
allow_lossNo
has_headerNo
verify_comNo

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. Changed5 schema fields changedv1.1.0
    • addedInput schema / properties / keys / description
      Added value: +"Sort keys, {column, order}; later keys break ties."
    • addedInput schema / properties / keys / items / properties
      Added value: +{
+  "column": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "minimum": 1,
+        "type": "integer"
+      }
+    ],
+    "description": "A column: a header name, a column letter, or a 1-based number."
+  },
+  "order": {
+    "enum": [
+      "asc",
+      "desc"
+    ],
+    "type": "string"
+  }
+}
    • addedInput schema / properties / keys / items / required
      Added value: +[
+  "column"
+]
    • addedInput schema / properties / keys / items / type
      Added value: +"object"
    • addedInput schema / properties / location / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "object"
+  }
+]
  3. First observedv1.0.0

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the readOnlyHint=false annotation, the description discloses many behavioral traits: rows are written back, formulas shift with Excel semantics, hidden rows stay pinned, uncalculated values produce warnings, hazardous workbooks require allow_loss, auto-backup is the undo mechanism, saving is atomic and verified, and the tool refuses while open in Excel. This is rich, non-obvious behavioral disclosure.

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 a single dense paragraph with the core purpose front-loaded. Every sentence adds a distinct fact about operation, parameter semantics, safety, or edge-case behavior. There is no filler or repetition of schema details.

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 mutating tool with no output schema and low schema coverage, this description is unusually complete: it covers key syntax, in-place mutation, formula behavior, filtered rows, safety flags, backup/undo, and file-lock refusal. The main gaps are the exact form of the required location parameter and the meaning/use of verify_com, plus the absence of any return/result contract.

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 only 13%, so the description must compensate for weak schema documentation. It does explain the central keys parameter well: list of {column, order}, header name/letter/1-based index, asc/desc, and tie-breaking. It also clarifies has_header and allow_loss. However, the required location parameter is only vaguely tied to 'range or table body' without stating accepted string/object forms, and sheet, path, and verify_com are not meaningfully explained.

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 a specific action and resource: 'Sort a range or table body by one or more keys, writing the rows back reordered.' This clearly distinguishes it from read, fetch, and other mutation tools. It also specifies the kind of target (range or table body) and the in-place reordering behavior.

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 conveys when to use this tool: when rows need to be reordered in place by one or more keys. It also gives practical context such as hidden-row behavior and safety requirements. It does not explicitly name alternatives or state when not to use it, which prevents a 5.

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