llm_price_changes

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

With no annotations supplied, the description carries the full behavioral burden and does well: it discloses the data provenance (~3,600 model/provider rows from LiteLLM direct prices and OpenRouter routed prices), the archive depth (weekly since 2026-05-23), the default comparison window, and roughly what each result row contains (old and new $/1M input and output, % move). It omits operational traits an agent might want — that it is a read-only operation, how the limit truncates results, and whether the current partial week is excluded.

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 opening sentence front-loads the core answer with the source and archive facts, and the 'Use for:' list converts abstract capability into recognizable queries. It is dense but every clause carries information; the model-count figure is the only element bordering on decorative.

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 six-parameter, zero-required read tool with no output schema, the description supplies the missing return-value context (the three change categories and the price fields reported) and the temporal defaults. What remains thin is how pagination/limit interacts with results and the exact granularity of a 'week' boundary.

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 83%, so the schema already documents query, since, until, source, and provider; the description only reinforces the default window ('latest week vs the week before'). It adds no syntax or interpretation guidance beyond the schema, and the 'limit' parameter's effect on result ordering is unexplained in both places.

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 — what changed in LLM token pricing between two archived weeks — and enumerates the three result categories (repriced, added, removed) plus the two upstream sources (LiteLLM, OpenRouter). It does not explicitly distinguish itself from close siblings such as compare_token_pricing, get_price_history, or lookup_extended_model_pricing, so an agent must infer the boundary from scope wording rather than being told.

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 'Use for:' clause gives four concrete example questions ('what got cheaper this week', 'did Anthropic or Bedrock change prices since October', 'new models on Groq this month', 'has Mistral Large's price moved') that map cleanly onto the query/provider/since parameters. It states when to use it but never says when not to, and names no alternative sibling tool for overlapping questions like current single-model pricing.

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