list_openrouter_models

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

With no annotations, the description carries the full burden and meets it: it discloses that the endpoint needs no API key and costs nothing, that ranking reads the catalog's own live fields so newly released models rank correctly, that cheap/fast/high-volume keywords flip tier preference, and that the tool must surface a price-annotated shortlist rather than silently pick an expensive model. This is far richer behavioral disclosure than the schema alone provides.

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?

Five dense sentences, all earning their place, with the core purpose front-loaded before the ranking and UX guidance. It is longer than minimal but every clause adds operational value; nothing reads as filler or repetition of the schema.

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 tool with no annotations and no output schema, the description covers a lot: returned fields, authentication/cost, ranking mechanics, keyword behavior, and user-presentation policy. The remaining gaps are minor — the exact response shape and failure behavior for the network fetch are left implicit — but nothing an agent needs to call it safely or correctly is missing.

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%, setting a baseline of 3. The description adds real meaning beyond the schema for the task parameter — explaining that ranking uses the catalog's own data and that keyword mentions of cheap/fast/high-volume redirect the ranking — and for interactive via the 'show the user and let them choose' guardrail. limit and refresh gain little beyond their schema text, so the bonus is partial.

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 names a specific verb and resource — 'List the live OpenRouter catalog' — and enumerates exactly what is included (~400 models, price per million tokens, context window, reasoning efforts). It is instantly distinguishable from list_ollama_models and list_atlas_models by naming the OpenRouter source, and from ask_openrouter by the explicit 'call it before' instruction.

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?

Explicitly says when to invoke it: 'call it before ask_openrouter rather than guessing a model id,' naming the sibling and the rationale. It also explains when the optional task-ranking path applies and how task phrasing alters results. It does not explicitly state when-not-to-use cases, but the primary alternative is named and the ordering is clear.

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