mcp-tools

AI API cost

ai_api_cost

Read-onlyIdempotent

Estimate AI API request, daily, and monthly costs in USD using token counts and model rates, with dated pricing snapshot provenance for token budget planning.

Instructions

Estimate API workload costs in USD per request, day and month, with rates and dated snapshot provenance. Use for token budgets; use ai_subscription_stack_cost for chat or coding subscriptions. Model IDs use providerId/id from https://operatornest.com/api/models?subset=pricing, filtered to the MCP catalog; the OSS bundle lists accepted IDs in src/data/pricing-snapshot.json. Rates stay offline until the catalog is updated; missing rates return null. Cached tokens are part of total input; published batch and long-context rates apply only when eligible. Non-token charges are excluded.

Input Schema

TableJSON Schema

Name	Required	Description
`modelIds`	Yes	Unique providerId/id values from the MCP pricing catalog. Unknown or unavailable IDs fail validation.
`inputTokens`	Yes	Total input tokens per request, including cached input tokens.
`outputTokens`	Yes	Generated output tokens per request.
`batchModelIds`	No	Optional subset of modelIds to price with published batch discounts. Omission or [] uses standard rates; IDs without a published discount are rejected.
`requestsPerDay`	Yes	Requests used to scale the daily estimate, independent of requestsPerMonth.
`requestsPerMonth`	Yes	Requests used to scale the monthly estimate; not inferred from the daily count.
`cachedInputTokens`	Yes	Cached portion of inputTokens per request; must not exceed inputTokens. Use 0 without caching.

Output Schema

TableJSON Schema

Name	Required	Description
`tool`	Yes	Calculator identifier for this result.
`input`	Yes	Normalized inputs used for this calculation.
`units`	Yes	Units for the numeric and time fields in this result.
`method`	Yes	Calculation or ranking method applied to the inputs.
`estimates`	Yes	Cost estimates in selected-model order.
`provenance`	Yes	Dated data sources or runtime time-zone information used for this result.
`assumptions`	Yes	Limits and assumptions to retain when presenting the result.

Schema Changelog

Changes observed during successful MCP inspections.

Changed53 schema fields changedv1.1.0Oct 3, 2026

changedInput schema / properties / batchModelIds / description

Previous value: -"Optional model IDs using a published batch discount."New value: +"Optional subset of modelIds to price with published batch discounts. Omission or [] uses standard rates; IDs without a published discount are rejected."

addedInput schema / properties / batchModelIds / examples
```
Added value: +[
+  []
+]
```

addedInput schema / properties / batchModelIds / items / description

Added value: +"Selected model ID with a published batch discount."

addedInput schema / properties / cachedInputTokens / description

Added value: +"Cached portion of inputTokens per request; must not exceed inputTokens. Use 0 without caching."

addedInput schema / properties / cachedInputTokens / examples
```
Added value: +[
+  5000
+]
```

addedInput schema / properties / inputTokens / description

Added value: +"Total input tokens per request, including cached input tokens."

addedInput schema / properties / inputTokens / examples
```
Added value: +[
+  10000
+]
```

addedInput schema / properties / modelIds / description

Added value: +"Unique providerId/id values from the MCP pricing catalog. Unknown or unavailable IDs fail validation."

addedInput schema / properties / modelIds / items / description

Added value: +"Model ID accepted by the MCP pricing catalog."

addedInput schema / properties / outputTokens / description
```
Added value: +"Generated output tokens per request."
```
addedInput schema / properties / outputTokens / examples
```
Added value: +[
+  2000
+]
```

addedInput schema / properties / requestsPerDay / description

Added value: +"Requests used to scale the daily estimate, independent of requestsPerMonth."

addedInput schema / properties / requestsPerDay / examples
```
Added value: +[
+  100
+]
```

addedInput schema / properties / requestsPerMonth / description

Added value: +"Requests used to scale the monthly estimate; not inferred from the daily count."

addedInput schema / properties / requestsPerMonth / examples
```
Added value: +[
+  3000
+]
```

addedOutput schema / description

Added value: +"API token cost estimates with normalized inputs, USD units, rate assumptions and catalog snapshot provenance."

addedOutput schema / properties / assumptions / description

Added value: +"Limits and assumptions to retain when presenting the result."

addedOutput schema / properties / estimates / description

Added value: +"Cost estimates in selected-model order."

addedOutput schema / properties / estimates / items / properties / batch / description
```
Added value: +"Whether a requested published batch discount was applied."
```
addedOutput schema / properties / estimates / items / properties / longContext / description
```
Added value: +"Whether published long-context rate multipliers apply."
```
addedOutput schema / properties / estimates / items / properties / modelId / description
```
Added value: +"Selected providerId/id from the pricing catalog."
```
addedOutput schema / properties / estimates / items / properties / name / description
```
Added value: +"Display name of the selected model or plan."
```
addedOutput schema / properties / estimates / items / properties / note / description
```
Added value: +"Catalog note about pricing limitations."
```

addedOutput schema / properties / estimates / items / properties / perDay / description

Added value: +"Estimated USD per day at requestsPerDay; null when rates are unlisted."

addedOutput schema / properties / estimates / items / properties / perMonth / description

Added value: +"Estimated USD per month at requestsPerMonth; null when rates are unlisted."

addedOutput schema / properties / estimates / items / properties / perRequest / description
```
Added value: +"Estimated USD per request; null when any required rate is unlisted."
```

addedOutput schema / properties / estimates / items / properties / ratesPerMillion / description

Added value: +"USD rates per million tokens after long-context multipliers, before batch discounts; null means unlisted."

addedOutput schema / properties / estimates / items / properties / ratesPerMillion / properties / cachedInput / description
```
Added value: +"Cached-input USD rate per million tokens; falls back to the input rate when absent."
```
addedOutput schema / properties / estimates / items / properties / ratesPerMillion / properties / input / description
```
Added value: +"Uncached-input USD rate per million tokens; null means unlisted."
```
addedOutput schema / properties / estimates / items / properties / ratesPerMillion / properties / output / description
```
Added value: +"Output USD rate per million tokens; null means unlisted."
```
addedOutput schema / properties / estimates / items / properties / sourceUrl / description
```
Added value: +"Official rate or scheduler syntax reference URL."
```

addedOutput schema / properties / input / description

Added value: +"Normalized inputs used for this calculation."

changedOutput schema / properties / input / properties / batchModelIds / description

Previous value: -"Optional model IDs using a published batch discount."New value: +"Optional subset of modelIds to price with published batch discounts. Omission or [] uses standard rates; IDs without a published discount are rejected."

addedOutput schema / properties / input / properties / batchModelIds / examples
```
Added value: +[
+  []
+]
```
addedOutput schema / properties / input / properties / batchModelIds / items / description
```
Added value: +"Selected model ID with a published batch discount."
```

addedOutput schema / properties / input / properties / cachedInputTokens / description

Added value: +"Cached portion of inputTokens per request; must not exceed inputTokens. Use 0 without caching."

addedOutput schema / properties / input / properties / cachedInputTokens / examples
```
Added value: +[
+  5000
+]
```

addedOutput schema / properties / input / properties / inputTokens / description

Added value: +"Total input tokens per request, including cached input tokens."

addedOutput schema / properties / input / properties / inputTokens / examples
```
Added value: +[
+  10000
+]
```

addedOutput schema / properties / input / properties / modelIds / description

Added value: +"Unique providerId/id values from the MCP pricing catalog. Unknown or unavailable IDs fail validation."

addedOutput schema / properties / input / properties / modelIds / items / description
```
Added value: +"Model ID accepted by the MCP pricing catalog."
```
addedOutput schema / properties / input / properties / outputTokens / description
```
Added value: +"Generated output tokens per request."
```
addedOutput schema / properties / input / properties / outputTokens / examples
```
Added value: +[
+  2000
+]
```

addedOutput schema / properties / input / properties / requestsPerDay / description

Added value: +"Requests used to scale the daily estimate, independent of requestsPerMonth."

addedOutput schema / properties / input / properties / requestsPerDay / examples
```
Added value: +[
+  100
+]
```

addedOutput schema / properties / input / properties / requestsPerMonth / description

Added value: +"Requests used to scale the monthly estimate; not inferred from the daily count."

addedOutput schema / properties / input / properties / requestsPerMonth / examples
```
Added value: +[
+  3000
+]
```

addedOutput schema / properties / method / description

Added value: +"Calculation or ranking method applied to the inputs."

addedOutput schema / properties / provenance / additionalProperties / description
```
Added value: +"Unit or source detail for the named field."
```

addedOutput schema / properties / provenance / description

Added value: +"Dated data sources or runtime time-zone information used for this result."

addedOutput schema / properties / tool / description

Added value: +"Calculator identifier for this result."

addedOutput schema / properties / units / additionalProperties / description
```
Added value: +"Unit or source detail for the named field."
```

addedOutput schema / properties / units / description

Added value: +"Units for the numeric and time fields in this result."

First observedv1.0.0Oct 2, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations declare a safe, offline, idempotent read, and the description adds real behavioral context beyond them: rates stay offline until the catalog updates, missing rates return null, cached tokens count inside total input, batch/long-context rates apply only when eligible, and non-token charges are excluded. These are exactly the operational caveats an agent needs to interpret results.

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?

Front-loads the core purpose before caveats, and every sentence carries information. Some sentences bundle several distinct caveats (cached tokens + batch rates + non-token charges), which makes it dense but not padded.

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

Completeness4/5

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

Covers provenance, failure behavior (null on missing rates), and pricing-eligibility edge cases for a 7-parameter estimation tool, and an output schema exists so return shape need not be described. Minor gaps remain around how the per-day/month windows are defined and whether zero-request inputs are valid.

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 already 100%, so the baseline is 3. The description adds cross-field meaning the schema does not spell out: modelIds follow providerId/id from a specific catalog, rates are dated snapshots, and batch eligibility is conditional. It stops short of explaining the interaction between requestsPerDay and requestsPerMonth beyond what the schema already states.

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 (Estimate), resource (API workload costs), unit (USD), and scope (per request, day, month), plus provenance. It explicitly distinguishes itself from the sibling ai_subscription_stack_cost, so an agent can route between them without opening a schema.

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 positive trigger (token budgets) and a named alternative with the condition that selects it (ai_subscription_stack_cost for chat or coding subscriptions). It also tells the agent where valid model IDs come from (the pricing catalog endpoint / OSS snapshot file).

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

Deploy Server