sort-excel-range

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

Annotations already declare destructiveHint=true, indicating a mutable operation, and the description adds no additional behavioral context. It does not explain whether sorting modifies data in place, whether it is reversible, or whether confirmation is needed. The description fails to capitalize on the lower bar set by annotations to provide useful context.

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?

The one-sentence description is extremely concise and front-loaded, but it is under-specified rather than appropriately sized. While there is no fluff, the brevity comes at the cost of essential information required for correct usage.

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?

Given the complexity of sorting an Excel range (multiple potential criteria, sorting in place, header handling), the description is woefully incomplete. There is no mention of return values, side effects, or required parameters beyond generic placeholders. The absence of an output schema and sparse description leaves even basics unexplained.

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?

The schema covers 86% of parameters with descriptions, but the critical 'body' parameter (which likely contains sort criteria) is only described as having an 'id' and allows additional properties. The description does not explain how to specify sort columns, order, or other options. With schema coverage high, baseline is 3, but the description adds nothing about the core sorting parameters, so a 2 is warranted as it fails to fill the domain-specific gaps.

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?

The description 'Sort an Excel range.' clearly states the verb (sort) and resource (Excel range), making the tool's basic purpose unambiguous. It is distinguishable from range operations like get, update, or clear by the specific action of sorting. However, it does not differentiate itself from potential sibling tools like inserting or formatting ranges, though those have distinct names.

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 description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites, required parameters like the sort key or order, or preconditions such as selecting a range. An agent would have to inspect the schema and infer usage, which is insufficient for a nuanced operation like sorting.

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