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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: per-row semantics (model×gateway rows), price units, the free filter behavior, and the canonicalSlug output contract. It doesn't describe pagination behavior or result counts, but for a read-only search this is solid supplementary 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?

Four short sentences, each earning its place: purpose, row semantics and units, filter behavior, and return contract with downstream routing. No filler, no repetition of schema content.

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?

Despite no output schema and 10 optional parameters, the description covers the essentials an agent needs: what is searched, result granularity, price units, the most important filter, and the key return field (canonicalSlug) plus how to use it downstream. The only gap is that pagination and sorting behavior are never acknowledged, leaving those inferred purely from parameter names.

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 70%, below the high-coverage baseline, with page, sort, and perPage lacking schema descriptions. The description doesn't compensate for those, though they are largely inferable from names, defaults and enum values. It does reiterates the free filter and adds that canonicalSlug is the useful output field, providing modest added meaning.

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+resource ('Search model offers across all gateways') and, crucially, defines the unit of each result ('one model at one gateway with its input/output price in USD per 1M tokens'). This row granularity plus the downstream-tool reference clearly sets it apart from siblings like list_gateways, suggest_models, and compare_model_prices.

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 gives clear usage context: search_models is the discovery step that 'Returns canonicalSlug for use with compare_model_prices and estimate_cost,' establishing the intended workflow. It also advertises the free=true shortcut. It does not explicitly state when NOT to use it versus siblings (e.g., list_gateways), so it stops short of a 5.

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