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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds behavior beyond them: results span every model and are ordered cheapest first. It does not mention currency, units, or whether pricing is current, but the key output-shape fact is disclosed despite no output schema.

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 with the core purpose front-loaded and the input requirement second; no filler, no restatement of the title.

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 read-only cost calculator with a fully documented four-parameter schema, the description gives enough to call it correctly and says what the result set looks like (all models, sorted cheapest first). Only minor gaps remain, such as units/currency and the batch-mode effect on results.

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 100%, so the schema already documents all four parameters including defaults. The description reinforces the input/output token meaning and gives a useful scaling frame ("per user per month") for the requests count, but leaves batch unmentioned; this is additive but marginal over the schema.

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 states a specific verb and resource ("Compare what the same workload costs on every Claude model") and adds scope ("every Claude model, cheapest first"), which separates it from a single-model cost estimate without needing to name the sibling.

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?

It tells the agent what to supply (tokens per request and request count, with a per-user-per-month example), which implies the comparison use case, but it never states when to prefer this over estimate_claude_cost or when-not to use it.

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