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

The readOnlyHint annotation covers the safety profile, so the description's added value is the returned field set (pricing, context window, max output, retirement date) and the catalog source, which help the agent judge result usefulness. It stops short of pagination, result limits, or error 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?

Three tight sentences, front-loaded with the returned data, followed by the usage trigger and the mode-dependent result shape. No filler.

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?

With no output schema and low parameter coverage, the description does the necessary work of listing return fields and explaining parameter-driven result shapes. Minor gaps remain around query matching semantics and list size limits.

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 only 33% (query and provider have no descriptions), so the description must compensate: it explains that model_id yields a single model while provider or query yields a list, which is the key semantic distinction. It does not clarify match behavior for query (substring vs. exact) or provider filtering.

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 resource (AI models) and the exact attributes returned — price per million tokens, context window, max output, retirement date — plus the data source (OpenRouter catalog). This clearly separates it from the package-oriented siblings such as find_package or package_status.

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?

Gives an explicit when-to-use trigger: 'before writing a model ID in code or estimating costs.' No exclusions or named alternatives are offered, but the guidance is concrete and actionable.

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