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

With no annotations present, the description carries the burden of behavioral disclosure and reveals a key limitation: shares are fractions (0-1) of sampled traffic and absolute volumes are not exposed. It also implicitly indicates time-windowed behavior and relative comparisons. This provides useful context beyond surface semantics, though it does not address potential rate limits, pagination, or detailed response format.

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?

The description is three sentences with no wasted words. The first sentence fronts the core purpose and output composition, the second provides usage direction, and the third states the key output caveat. It is dense with relevant information and remains concise.

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?

The description illustrates the output structure (per-type breakdown, top models, macro-category aggregates) and clarifies the numeric semantics (fractions, no absolute volumes). Given the simple parameter set and no output schema, the description already answers most of the an agent needs for correct invocation. It does not mention authentication or rate limits/expectations, but these are unlikely to affect the call itself.

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 only parameter, `window`, is already fully documented in the schema with an enum, default, and description. The tool description merely restates 'trailing window' and does not add grain of truth role coverage or alternative usage details. This matches the baseline 3 for a schema with high description coverage.

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 uses a clear verb-plus-resource construction: 'See what OpenRouter traffic is actually used for' and then specifies a market-share breakdown by task type, top models per task, and macro-category aggregates. This is distinctive from sibling tools like list_models or list_providers, even though no sibling is named. The full range of output is identified precisely.

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 includes an explicit use directive: 'Use to learn which models real usage favors for a given kind of work.' This gives clear guidance on when to invoke it. It does not explicitly contrast with siblings or mention when not to use it, but the intended use case is unambiguous and sufficient for an agent to choose it over alternatives.

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