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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower here. The description adds real operational context beyond that: 'free routes only' scopes the data and 'prices are collected from provider pages and can lag' discloses a freshness/reliability caveat that annotations cannot express.

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?

Front-loaded with the tool's identity, then a compact action map, a usage line, and a limits line. Every sentence carries information with no filler, though the semicolon-chained action list is dense and slightly harder to scan than a structured list.

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 6-param, zero-required action router with no output schema, the description covers action semantics, key param bindings, usage intent, and limits. Missing only the 'limit' parameter meaning and any default/return-shape hints, which are minor given annotations carry the safety profile.

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?

With only 50% schema description coverage, the description compensates well by binding parameters to actions (q for search, model_id for price_current, dataset for sample, days<=7 for price_changes_recent). It even adds a constraint not present in the schema. Only 'limit' is left unexplained, keeping it below a 5.

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 gives specific verbs and resources for each action (catalog lists endpoints/datasets, search resolves names, price_current returns per-token prices, price_changes_recent lists changes, sample returns raw rows). An agent can tell exactly what surface the tool covers. It does not explicitly distinguish itself from any sibling, but no sibling overlaps this data domain.

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?

It offers one usage cue ('Use it to compare LLM API costs') plus a constraint (last days <= 7), which implies when to reach for it. However, it never states when NOT to use it or how the actions relate to alternatives, and there is no explicit when-to-use routing beyond the action list itself.

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