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

With readOnlyHint already declaring a safe read, the description adds genuine behavior: default ordering is priced offers first with doubtful prices demoted after sane ones, and price units are USD per 1M tokens or per unit. It does not state pagination or result-count cap behavior beyond the schema's limit default, which keeps it from a 5.

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 sentences, front-loaded with purpose then breadcrumbs for next steps; the row-field list is dense but useful. Minor noise from the internal ticket reference '(WP-0086)' and some telegraphic phrasing, but no sentence is redundant.

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 9-parameter, fully optional search tool with no output schema, the description compensates by enumerating the returned row fields and the ordering rule. It is nearly complete; the only gap is the relationship to the sibling cheapest_offers search, which an agent must infer.

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 description coverage is 100% with per-parameter descriptions and enums, so the schema does the heavy lifting. The description only restates the searchable axes (words, model type, limits) and does not clarify ambiguous parameters such as 'multi', 'free_only' interaction, or price-unit vs token-price sorting semantics.

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 and resource ('Search current AI model offers') and defines the unit precisely: one model at one provider = one offer. It also describes the result entity (offer_id, model_id, provider_id, per-1M prices, card_url, cite) and the ordering policy, so an agent knows exactly what comes back 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 'Next:' clause explicitly routes the agent to get_card for a single offer, get_model_prices for a model across providers, and estimate_cost / cheapest_for_workload for costing, which is strong follow-on guidance. It does not, however, draw the boundary against the sibling search tool cheapest_offers, so the choice between the two search entry points is left implicit.

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