sort_rangeSort rows in an Excel range by one or more columns, ascending or descending, while keeping entire rows intact.
Sort a range's rows by one or more columns, like Data > Sort in Excel.
Rows move whole. Key columns must hold values, not formulas; no merged cells.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| range | Yes | ||
| sheet | Yes | ||
| sort_by | Yes | Columns to sort by, most important first. | |
| has_header | No | First row stays in place. |
Changes observed during successful MCP inspections.
v2.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and non-idempotent, so safety is partly covered. The description adds real behavioral context beyond that: 'Rows move whole' clarifies that entire rows are reordered (not just the key columns), and the formula/merged-cell constraints are operation-specific traits an agent must know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero waste; the core operation is front-loaded before the constraints. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with an output schema absent and only 40% param coverage, the description covers the operation, the row-movement semantics, and preconditions well. It falls slightly short of fully compensating for the undocumented parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40%, so the description should compensate but adds little parameter-specific detail. It does hint that multiple key columns are supported and that key columns must hold values rather than formulas, but says nothing about path, sheet, range, has_header, or the ascending/descending option.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (sort) and resource (a range's rows by one or more columns), and the 'Data > Sort in Excel' analogy pins the exact operation. An agent can distinguish this from siblings like transform_range or copy_range without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'like Data > Sort in Excel' analogy and the preconditions ('key columns must hold values, not formulas; no merged cells') give implied usage and setup requirements. However, it never states when to use this versus alternatives such as transform_range, nor any when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.