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), and the description adds real behavior beyond that: prices are dated and sourced from provider pages, the returned fields include the checked date and source page, Anthropic-specific cache and fast-mode rates are enumerated, and unknown models return the sentinel UNPRICED rather than $0. The "public read (no auth)" note is exactly the kind of context 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 purpose, then return contents, then two concrete invocation examples including a literal argument object, then the auth note. Every sentence carries information, but the parenthetical enumerating cache rate types is dense and slightly harder to scan than the rest.

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?

There is no output schema, so the description must carry the return shape, and it does: per-1M-token USD rates, checked date, source page, and a cost breakdown. Auth, currency, rate units, and the UNPRICED edge case are all covered. Minor gaps remain around cost-breakdown structure (whether a total is included) and rounding precision.

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 description coverage is only 29%, so the description must compensate, and it largely does: it explains that token counts turn the lookup into a cost computation, that omitting model lists everything, that cache write rates split into 5-minute and 1-hour, and that fast mode is a premium Anthropic rate. It does not spell out per-parameter behavior for each of the four token fields (e.g. how cache_write_1h_tokens interacts with cache_read_tokens), leaving some mapping to inference.

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 verb and resource: "Looks up what an AI model or an agent session costs at list price." It also scopes the data source ("copied from each provider's own pricing page") and names the two modes (list all models vs. compute cost). None of the sibling tools (check-package, search, enrich-ioc, etc.) overlap, so no differentiation is needed.

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 explicit invocation contexts: no args lists every priced model with checked dates; passing token counts yields an exact cost for a call or session. It also states the edge-case behavior (UNPRICED, never $0) and that no auth is required. It stops short of stating when an agent should prefer this over estimating from memory, but with unrelated siblings no alternative routing is required.

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