list_availability

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

With no annotations, the description carries the full behavioral burden and does add real value: it distinguishes live (refreshed at most every 6 hours) from curated data, which tells the agent the snapshot can be up to 6 hours stale. It stops short of covering auth requirements or what happens on upstream failure.

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?

A single dense sentence with the resource and both data sources front-loaded and zero filler. The parenthetical refresh cadence is the one detail that earns its place.

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 no-param, no-annotation, no-output-schema read tool, the description covers what categories of data come back and how fresh they are, which is the main thing an agent needs. It could say slightly more about the shape/nesting of the returned snapshot, but the coverage is reasonable.

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?

The tool takes zero parameters, so there is no per-parameter semantics to add; baseline for a parameterless tool is 4.

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?

Names a specific verb+resource ('list_availability') and states precisely what the snapshot contains: live OpenRouter listing status plus curated Bedrock/Vertex/Foundry region coverage. It is clear on its own, but it never differentiates itself from the sibling list_models, which an agent could easily confuse it with.

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?

No explicit when-to-use or when-not-to-use guidance, and no routing to alternatives like list_models or suggest_models. The 6-hour refresh note implicitly signals the freshness trade-off, but the agent must infer that this tool is the one to call for provider/region availability rather than model metadata.

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