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

Annotations already mark the tool read-only and non-destructive. The description adds meaningful behavior beyond that: it is a paid call ('US$0.02 per successful autonomous x402 call') and serves data from an 'already-warmed canonical model cache,' which clarifies cost and freshness characteristics. No contradiction with annotations.

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 short sentences carry high-value information: cost/credit and source/cache semantics are front-loaded, followed by the core action. Every clause earns its place and there is no redundant restatement of the tool name.

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 simple read-only tool with one optional integer parameter, the description covers cost, data source, and result type. It does not spell out the exact ranking format or default limit, but the annotations and schema cover the rest, so nothing critical is missing for a competent agent.

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 single optional 'limit' parameter is self-explanatory from its name and 1–500 bounds in the schema, but the description adds no detail about how limit affects the returned rankings or what the default behavior is. With 0% schema description coverage, some compensation would have been helpful, though the parameter is simple enough to remain usable.

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 opens with a specific action and object: 'Return current derived Horse Truth rankings.' That is a clear verb+resource statement, and 'rankings' differentiates it from sibling snapshot, change, and compare tools without requiring the agent to open schemas.

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 this tool is for retrieving current rankings and prominently warns that calls are paid, but it never states when to prefer it over siblings such as horse_snapshot or horse_signal, nor does it mention any exclusions. The payment warning is useful context but not explicit selection guidance.

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