ModelCostComparison

compare_model_costs

Read-onlyIdempotent

Use when you already have 2–20 exact offer IDs and want their USD text-token subtotals for the same usage and pricing snapshot. Equal token counts are a comparison assumption, not equivalent tokenization of the same text. Returns supported results and per-offer exclusions. Excludes cache writes, storage, search, tool fees and taxes; does not rank quality. Use find_cheapest_models to search without a shortlist.

Input Schema

TableJSON Schema

Name	Required	Description
`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.
`model_ids`	Yes	Distinct exact pricing-offer IDs returned by discovery. Choose 2–20 offers to compare; do not supply display names.
`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.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 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 / model_ids / description

Added value: +"Distinct exact pricing-offer IDs returned by discovery. Choose 2–20 offers to compare; do not supply display names."

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."

First observedSep 25, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive). The description adds substantive behavior: the equal-token-count comparison assumption, that per-offer exclusions are returned, and an explicit exclusion list (cache writes, storage, search, tool fees, taxes), plus the caveat that it does not rank quality.

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

Conciseness5/5

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

Front-loads the precondition, then caveats, then exclusions, then the sibling routing. Every sentence carries distinct, actionable information with no padding.

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?

An output schema exists, so return shapes need not be explained, yet the description still flags 'supported results and per-offer exclusions'. Combined with the documented usage shape and the DATASET_CHANGED handling in the schema, an agent has everything needed to invoke and interpret it.

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

Parameters3/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. The description reinforces 'exact offer IDs' and 'do not supply display names' and the 2–20 bound, but these are already documented in the schema, so it adds little beyond reinforcement.

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

Purpose5/5

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

States a specific verb and resource ('compare' cost subtotals for 2–20 exact offer IDs) and scopes it tightly. It is immediately distinguishable from discovery/ranking siblings like find_cheapest_models.

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

Usage Guidelines5/5

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

Opens with the precise precondition (you already have 2–20 exact offer IDs) and names the alternative with the condition that selects it ('Use find_cheapest_models to search without a shortlist'). When-to-use, when-not, and alternative are all explicit.

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.