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

With no annotations provided, the description must disclose behavior such as that it only works with numeric columns and that the default order is descending (highest first). The description does not mention these limitations or default behaviors, nor does it indicate what the output format is, leaving the agent to infer behavior.

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 description is one sentence and directly states the purpose, including the key use case. It is front-loaded with the action and scope, and every word contributes to understanding, with no wasted information.

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 simple functionality (ranking rows), the description is somewhat adequate but lacks details on numeric column requirements, default ordering, and output format. The absence of an output schema means the description should have clarified return values, but it does not. The complexity is moderate, so a 3 is appropriate.

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 provides minimal coverage (33%) as only the 'ascending' parameter has a description. The tool description does not elaborate on the 'column' or 'limit' parameters beyond what the schema shows, but the description's mention of 'highest (or lowest) rows' partially clarifies the 'ascending' parameter. The description adds some context but does not fully compensate for the low schema coverage, especially for the required 'column' parameter.

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 clearly states that it ranks rows by a numeric column, and the phrase 'highest (or lowest) rows' indicates the core functionality. It distinguishes itself from siblings by focusing on ranking/ordering rather than searching or retrieving individual rows, but it does not explicitly name a sibling to distinguish from.

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 implies usage for answering 'which is the most/least X' questions, which provides context. However, it does not explicitly state when to use this tool versus alternatives like dataset_search or dataset_stats, nor does it mention any prerequisites such as the column being numeric or the need to check available columns via dataset_columns.

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