ModelCostComparison

find_cheapest_models

Read-onlyIdempotent

Use when you know your token workload but have not selected offers: rank eligible current reviewed offers by USD text-token subtotal and return their exact IDs. Defaults to standard tariffs. Cheapest means within the eligible catalogue and supplied filters, not best quality or the entire market. Equal token counts do not imply tokenizer equivalence. Excludes cache writes, storage, search, tool fees and taxes; reports exclusion counts. Optional capacity filtering uses reviewed pricing input limits, not full context windows.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum ranked results to return: 1–20; default 10.
`usage`	Yes	Token totals for the period or scenario being estimated, not dollars or request counts. Supply input and output separately; cached input is a subset of total input.
`provider_id`	No	Optional exact provider_id returned by list_providers or offer identity. Use to restrict results to one provider; omit for all providers.
`pricing_tier`	No	Optional exact tariff name from offer identity, such as standard or peak. Omit to rank standard tariffs.	standard
`expected_dataset_revision`	No	Optional consistency check: copy meta.dataset_revision from a prior tool response to require the same current pricing snapshot. Omit to use the current snapshot. A mismatch returns DATASET_CHANGED; refresh pricing and retry. This cannot retrieve a historical snapshot.
`min_input_tokens_per_request`	No	Optional minimum reviewed per-request pricing input limit an offer must support. Unknown or smaller limits are excluded. This is not the model context window and does not replace usage.max_input_tokens_per_request.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedSep 29, 2026

addedInput schema / properties / expected_dataset_revision / description

Added value: +"Optional consistency check: copy meta.dataset_revision from a prior tool response to require the same current pricing snapshot. Omit to use the current snapshot. A mismatch returns DATASET_CHANGED; refresh pricing and retry. This cannot retrieve a historical snapshot."

addedInput schema / properties / limit / description

Added value: +"Maximum ranked results to return: 1–20; default 10."

addedInput schema / properties / min_input_tokens_per_request / description

Added value: +"Optional minimum reviewed per-request pricing input limit an offer must support. Unknown or smaller limits are excluded. This is not the model context window and does not replace usage.max_input_tokens_per_request."

addedInput schema / properties / pricing_tier / description

Added value: +"Optional exact tariff name from offer identity, such as standard or peak. Omit to rank standard tariffs."

addedInput schema / properties / provider_id / description

Added value: +"Optional exact provider_id returned by list_providers or offer identity. Use to restrict results to one provider; omit for all providers."

addedInput schema / properties / usage / description

Added value: +"Token totals for the period or scenario being estimated, not dollars or request counts. Supply input and output separately; cached input is a subset of total input."

addedInput schema / properties / usage / properties / cached_input_tokens / description

Added value: +"Number of input_tokens expected to be cached, not additional input. Defaults to 0 and must not exceed input_tokens. Cache-write charges are excluded; an unconfirmed cache discount falls back to ordinary input pricing with a warning."

addedInput schema / properties / usage / properties / input_tokens / description

Added value: +"Total input tokens across the workload, including cached input. For monthly estimates, sum input over all monthly requests."

addedInput schema / properties / usage / properties / max_input_tokens_per_request / description

Added value: +"Largest full input in any single request, including cached tokens; not the monthly total or average. Provide when a tariff has an input limit so eligibility can be checked."

addedInput schema / properties / usage / properties / output_tokens / description

Added value: +"Total billable output tokens across the same workload period, including billed reasoning tokens where applicable."

AddedSep 27, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses the exact cost scope excluded (cache writes, storage, search, tool fees, taxes), that exclusion counts are reported, that the default tariff is standard, and that equal token counts do not imply tokenizer equivalence. These are non-obvious behavioral traits an agent cannot infer from the annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single dense paragraph that front-loads the usage trigger and then layers scope caveats; every sentence carries information. It would be easier to scan as short bullets, but there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter ranking tool with an output schema and rich annotations, the description covers eligibility, cost exclusions, tariff defaults, capacity-filter semantics, and the tokenizer caveat. An agent has enough to invoke it correctly without guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: that capacity filtering reflects reviewed pricing input limits rather than full context windows, and that token-count parity across models is not tokenizer equivalence. It otherwise restates schema facts such as the standard-tariff default, keeping it below 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: rank eligible current reviewed offers by USD text-token subtotal and return their exact IDs. It also pins down what 'cheapest' means (within eligible catalogue and supplied filters, not quality or whole market), which helps separate it from compare_model_costs. It stops short of naming sibling tools, so it falls one notch below a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The opening 'Use when you know your token workload but have not selected offers' states a clear triggering condition, and the 'not best quality or the entire market' caveat bounds expectations. No alternative tool is named for the adjacent case (e.g., when you already have offers or want a pairwise comparison), so there is no explicit when-not routing.

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

All ModelCostComparison tools Inspect

Try in Browser

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.