Skip to main content
Glama
KitchenSink4AI

io.github.nometalalchemist/kitchensink4xl

by KitchenSink4AI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Sort Range

sort_range
Destructive

Sorts rows by one or more columns (header, letter, index) in asc/desc order, keeping headers and hidden rows pinned. Preserves formulas and references in Excel.

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 annotations (destructiveHint=true, readOnlyHint=false), the description discloses critical behaviors: formula relative reference shifting, cached value comparison with warnings for uncalculated cells, pinned filter-hidden rows, auto-backup with undo capability, atomic verified save, and refusal when open in Excel. This rich detail greatly exceeds what annotations alone convey.

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 dense yet well-organized, opening with the core purpose, then the key parameter semantics, followed by behavioral notes. Every sentence adds value, and there is no redundancy or filler. The length is justified by the tool's complexity and the need to convey safety-critical behavior.

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 tool with 8 parameters and low schema coverage, the description covers the main operational semantics, safety requirements, and error conditions. It addresses formula handling, hidden rows, and open-workbook refusal. Some parameters remain under-specified, but the essential information for correct invocation is present, making it reasonably complete.

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?

The description explains the keys parameter thoroughly (list of {column, order}, column types, tie-breaking) and clarifies has_header ('keeps the first row put'). It also implies allow_loss and backup behavior. However, with schema coverage at only 13%, several parameters (path, sheet, location, verify_com) lack explicit elaboration in the description, so it only partially compensates for the low schema coverage.

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 states a specific verb ('Sort') and resource ('a range or table body') with clear details about writing rows back reordered. It differentiates from sibling range operations (e.g., copy_range, clear_range, query_range) by focusing solely on sorting semantics, leaving no ambiguity about the tool's role.

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 strong contextual usage guidance, such as how filter-hidden rows are handled, the need for allow_loss on hazardous workbooks, and refusal while open in Excel. It does not explicitly name alternative tools, but since no sibling tool performs sorting, the intended usage is clear and unambiguous.

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