ModelCostComparison

calculate_cost

Read-onlyIdempotent

Use when you have one exact offer ID and token usage and want its USD text-token subtotal. Discover the ID with list_models first. Total input includes cached input; do not add cached tokens twice. Excludes cache writes, storage, search, tool fees and taxes. Requires current reviewed, supported rates; does not invoke a model. Use compare_model_costs for several known offers.

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_id`	Yes	Exact pricing-offer ID returned by list_models or find_cheapest_models. Do not substitute a display name or guessed API model name.
`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_id / description

Added value: +"Exact pricing-offer ID returned by list_models or find_cheapest_models. Do not substitute a display name or guessed API model name."

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.9/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavioral context beyond them: what is excluded (cache writes, storage, search, tool fees, taxes), that it does not invoke a model, that it requires current reviewed supported rates, and the double-counting caveat for cached input.

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?

Five tight sentences, front-loaded with the use case, then prerequisite, then inclusions/exclusions, then alternative. Every sentence carries distinct information with no filler.

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 read-only calculation tool with a full output schema (so return values need not be explained), the description covers scope, prerequisites, exclusions, rate requirements, and sibling routing. An agent has everything needed to invoke it correctly.

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 coverage is 100%, so the baseline is 3, but the description adds real semantic value by clarifying that total input already includes cached input and warning not to add cached tokens twice. It does not add further syntax detail beyond what the schema already provides.

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 (calculate) and resource (cost) with precise scope ('USD text-token subtotal' for 'one exact offer ID and token usage'). It explicitly distinguishes itself from siblings by naming compare_model_costs for multiple offers and list_models for ID discovery.

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?

Gives an explicit trigger condition ('when you have one exact offer ID and token usage'), a prerequisite step ('Discover the ID with list_models first'), and a named alternative with its selecting condition ('Use compare_model_costs for several known offers'). Nothing is left to inference.

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.