compare_token_pricing

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

With no annotations, the description carries the full burden and does well: it discloses the ranking algorithm and how it changes based on inputs, and that cache_read / cache_write rates are surfaced only 'when published' — an important availability caveat. It does not state currency, pagination, or whether results include all providers by default, leaving minor behavioral gaps for a read-only pricing lookup.

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 core differentiator, then filters, then ranking logic, then cache caveat — a sensible information order. It is somewhat long and carries mild promotional framing ('the only FinOps tool', '30-90% input cost reduction'), but the parenthetical provider mappings and the ranking rule both earn their space.

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 convey return values, and it does: per-1M input/output rates, monthly_total_usd, cache_read/cache_write rates when published, plus the sort order applied. For a five-parameter, zero-required read-only comparison tool this is nearly complete; currency and default provider coverage are the only unstated details.

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 100%, so the schema already documents all five parameters, including enum values and the note that monthly token volumes are required to receive monthly_total_usd. The description restates the model_family enum and adds the combined ranking effect of the two token-volume parameters, which is modest added value over an already complete schema — the baseline 3 applies.

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 ('cross-provider LLM token pricing comparison') and enumerates exactly what is returned: per-1M input/output rates plus monthly cost for the same model on each hosting provider, with concrete examples (Claude on Anthropic vs Bedrock vs Vertex). The claim 'the only FinOps tool that returns per-1M input/output rates AND monthly cost' positions it against siblings such as lookup_extended_model_pricing and compare_llm_vs_selfhost without the agent needing to open either schema.

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 clear conditional usage semantics: supply monthly_input_tokens + monthly_output_tokens to rank by total monthly USD, otherwise results rank by per-1M output cost because 'output tokens dominate most workloads.' Filter dimensions (model_family, model_id, providers) are each framed by when to use them. The only gap is that no alternative sibling is named with an explicit 'use X instead when…' clause.

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