MCP Tool Reference

Most users do not need to call these tools by name. Ask your AI assistant the financial question you want answered and let it choose the appropriate Ternary capabilities.

For user-oriented examples, see What you can do and Example questions.

Tool index

Access and discovery

ternary_list_tenants

Lists the Ternary tenants available to the authenticated user.

Typical use: the assistant needs to determine which organization or tenant a question refers to.

Reads / writes: reads.

Other tenant-scoped tools use a tenantID returned from this list.

---

ternary_list_dimensions

Lists every dimension and measure available for a tenant in one call. The assistant uses this before a query so it can work with real Ternary field names instead of inventing schema fields.

Fields are grouped by namespace — FOCUS fields, each provider's billing export, Custom Labels, provider tags, custom measures — and listed by name. A group whose fields Ternary reads in a particular way, such as Custom Labels, the AI classification fields, or provider tags, carries that rule above its names, so the assistant knows which field to prefer when two look alike.

Typical use:

• Find the provider dimension
• Find service or account fields
• Discover tenant-specific fields available for grouping or filtering

Reads / writes: reads.

Important limitations:

• The whole catalog comes back in one response; there is no paging. A catalog too large to fit lists its provider-tag groups as counts, and the assistant can ask for one of those groups by its namespace
• The catalog lists names only. What a field means, its data type, and its unit come from ternary_describe_fields
• Search matches field names, display names, and namespaces, not descriptions. A business word such as "vendor" or "refund" is rarely part of a field's name, so the assistant reads the full catalog instead

Important: field discovery is a technical step. Users can ask in business language rather than supplying schema field names themselves.

---

ternary_describe_fields

Explains what named fields mean. For each field it returns the full description, the data type, whether it is a measure, and for a measure its unit, such as currency or percentage.

The assistant uses this when two fields look alike, such as BilledCost and EffectiveCost, or before it treats a measure as money.

Typical use:

What is the difference between billed cost and effective cost?

Which of these fields is in dollars?

Reads / writes: reads.

Important limitations:

• Fields are named by their exact schema field name, as returned by ternary_list_dimensions
• Up to 50 fields per call
• A name that is not a field of the tenant is listed back rather than described; the other names in the call are still described
• Long descriptions are shortened when a call asks for many fields at once; the assistant can ask for fewer fields to see each in full

---

ternary_get_dimension_values

Returns recent distinct values for a dimension. The assistant can use this to discover real values before applying a filter.

Example: after finding a service-name dimension, the assistant can retrieve actual service names before filtering for one of them.

Reads / writes: reads.

Important: sampled values are useful for discovery and should not be treated as a complete historical catalog for every period.

Cost analysis

ternary_run_cost_query

Runs an ad-hoc cost or usage query.

The query can define:

• Date range
• Grouping dimensions
• Measures
• Filters
• Time precision

The response returns the largest groups first and includes a server-computed summary with:

• Exact total for the requested range
• Coverage of the returned rows

ternary_run_cost_query returns up to 100 rows by default; the requested limit can be 1–1,000. Response-size limits can return fewer rows than requested. Use hasMore, nextPageToken and notes to determine whether the result continues. Send the returned token as pageToken with the same query arguments; keep the resolved date range unchanged across pages.

Default cost queries cover the last thirty complete UTC days, excluding today.

Current data source: FOCUS_BILLING

Typical use:

Show last month's spend by provider.

Show AWS spend by service for August.

Reads / writes: reads.

Important limitations:

• Non-FOCUS data sources are not currently available through this tool
• General period-over-period comparison can require multiple calls and host-side arithmetic
• Scope, period, currency, measure, and coverage should remain explicit in finance-critical interpretation

Label coverage

ternary_get_label_coverage

Measures how much of a tenant's spend one label covers over a time window. It is built for Custom Labels used for chargeback, such as a department, product, or budget code. It also accepts a provider tag.

Can return:

• Total, allocated, and unallocated spend, and the coverage percentage
• The same figures for each cloud provider, largest gap first
• Spend for each label value
• The Custom Label rules that write the label, with their status and a link to each
• Values that look like a misspelling of a larger value, and empty or placeholder values such as unknown or n/a

On request, it can also return:

• Where the unallocated spend sits: the 20 largest account and service pairs, plus the amount outside them
• Values that are not on a list of approved values you give it
• Spend that has the label but is missing a second label that should always come with it

Unallocated means the label is not set on the billing row. This is the same as a "not set" filter in a report, so the figures match a report built that way.

Defaults to the last thirty complete UTC days, excluding today, and to billed cost.

Typical use:

How much of last month's spend has a department label?

Where is the spend with no product label?

Which budget codes look misspelled, and how much spend sits on them?

Reads / writes: reads.

Credits can make label coverage fall below 0% or exceed 100%. When total spend is zero, coverage is null; it is not a measured 0% allocation rate. Read coverage together with the total, allocated and unallocated amounts.

Provider and label-value detail can be partial when source groups reach their limits. Check notes before treating an absent value or provider gap as zero. Coverage can still be returned when Custom Label rule access is denied; a permission_denied rule status describes missing rule context, not a failed spend-coverage calculation.

Important limitations:

• One label per question
• The measure must be a cost column: billed, effective, list, or contracted cost
• A row whose label value is an empty string counts as allocated. The tool lists it as an empty value instead
• The misspelling check is a heuristic. Treat its results as values to review, not as confirmed errors
• The list of approved values is given with each question; Ternary does not store it
• Up to 20 rules are listed for a label
• Each list of values to review shows its 20 largest entries

Reports

ternary_list_reports

Lists saved reports for a tenant.

Supports name-based search.

Typical use:

Find our Monthly Executive Summary report.

Reads / writes: reads.

---

ternary_get_report_data

Retrieves rows from a saved report one page at a time.

Typical use:

Show the data from the Monthly Executive Summary report.

Reads / writes: reads.

For ternary_get_report_data, the default is 100 rows and the supported limit is 1–1,000, subject to response-size limits. When hasMore is true, pass nextPageToken as pageToken with the same reportID. A short page alone does not establish that the report is complete.

Important: a saved report carries business meaning from its configuration. The assistant should avoid guessing missing semantics if the available response does not make them explicit.

---

ternary_create_report

Creates a private saved report from a cost-query configuration.

This is the only current Ternary MCP write capability.

The report is:

• Saved privately to the authenticated user
• Visible in Ternary saved reports
• Created only when the user explicitly asks to keep the analysis

Save a compatible report

Before saving, check that the analysis fits the report configuration. ternary_create_report accepts individual dimension filters combined with AND, using equality, inequality, containment and set/not-set operators. It does not save composite filter groups or numeric comparisons supported by ad-hoc cost queries.

Choose a compatible presentation. Table is the default; for example, a KPI needs one measure and no dimensions, and a top-item KPI needs one dimension. Chart, measure, dimension and comparison settings are validated before creation.

Choose either a rolling relative period or both fixed date boundaries. Relative reports keep moving and can include today when opened, so their figures can differ from the complete-day ad-hoc query. Fixed reports store whole UTC days, including the end day; timestamp cutoffs are discarded. Saving is therefore not a lossless replay of every ad-hoc query.

Recover an uncertain report save

Report creation is not idempotent and names are not unique. A failed preview or readback can occur after the report is saved. Before retrying an uncertain save, search for a recent report with the exact requested name. Confirm which report matches the intended save before reusing it; if matches are ambiguous, resolve which report was created before retrying.

MCP cannot currently update or delete the report afterward.

Reads / writes: writes.

Budgets

ternary_list_budgets

Lists budgets with the current figures shown by the Ternary budget evaluation.

The result can include:

• Budget amount
• Actual spend
• Projected month-end spend
• Health status
• Evaluation period

Budgets are ordered with the most severe statuses first and can be filtered by status.

Typical use:

Which budgets are over budget or at risk?

Reads / writes: reads.

A health-status filter matches a budget or any of its sub-budgets, so an on-track parent may appear when an over-budget child matches. Inspect both levels. NOT_EVALUATED indicates an unavailable evaluation, including unsupported amounts or missing evaluation data; unavailable amounts are not zero spend or evidence that the budget is on track.

Important limitations:

• Budget figures are a snapshot from the last evaluation
• The period can predate the current month
• No month-by-month history is exposed
• The budget projection is not the Ternary Forecasting product

Dashboards

ternary_list_dashboards

Lists dashboards available to the user. Supports name-based search.

Reads / writes: reads.

---

ternary_get_dashboard_definition

Describes the composition of a dashboard. The result can identify widgets in reading order and resolve the report or budget represented by supported widgets.

Typical use:

What is included in the Executive dashboard?

Reads / writes: reads.

---

ternary_get_dashboard_delta

Compares supported dashboard report widgets across two time windows.

Can return:

• Current value
• Prior value
• Absolute change
• Percentage change
• Groups with the largest movements

The default comparison is the last seven full days against the seven full days before them.

Typical use:

What changed on the Executive dashboard?

Reads / writes: reads.

Important limitations:

• Up to 15 report widgets are compared per call
• Unsupported widgets are disclosed rather than assigned a misleading value
• Non-summable measures may not be compared
• Budget widgets pass through their evaluated status
• Invoice-month reports are compared over usage timestamps rather than their normal invoice-month accrual basis

Cost alerts

ternary_list_cost_alerts

Lists alerts fired by the tenant's Ternary cost rules.

Covers:

• Anomaly detections
• Threshold breaches

Can return:

• Observed value
• Baseline
• Alert status
• Rule context

Cost alerts default to the start of the UTC day thirty days ago through the end of today (UTC). Compare the echoed date bounds before reconciling spend with alert results; use explicit matching bounds when you need the same period.

Typical use:

Which cost alerts fired this month?

Reads / writes: reads.

Reading fired cost alerts and reading their rules require separate permissions. An event response can succeed without rule details or a rule summary when rule access is denied. In that case, text search covers visible dimension values but cannot search rule names; the response includes an incompleteness note. Missing rule context does not mean that no event occurred. Without event-read permission, the request fails.

Important limitations:

• The tool reads Ternary detections; it does not independently invent anomalies
• The rule shown is its current configuration
• Alert status is a user-managed triage status

Savings recommendations

ternary_list_recommendations

Lists current savings recommendations, ordered by estimated monthly savings.

Can cover supported optimization types such as:

• Idle resources
• Rightsizing
• Other currently applicable recommendations

Can be filtered by supported provider and state.

Typical use:

What are our largest current savings opportunities?

Reads / writes: reads.

Important limitations:

• Commitment inventory and commitment recommendations are not currently exposed
• The recommendation view reflects currently applicable recommendations from the current recommendation window

AI spend and revenue

ternary_get_ai_roi

Weighs AI spend against revenue over a time window, for the whole tenant and for each value of one Custom Label, such as each product or team.

Can return:

• AI cost
• Revenue
• The ratios between AI cost and revenue

AI ROI defaults to the start of the UTC day thirty days ago through the end of today (UTC); label coverage uses the last thirty complete UTC days, excluding today. Set matching explicit dates when comparing them.

Typical use:

How does our AI spend compare with revenue this month?

Show AI cost against revenue by product for last quarter.

Reads / writes: reads.

Tenant revenue can exist while per-label ratios are null because it is not attributed to the selected label. A zero placeholder for unattributed per-value revenue does not mean the tenant earned no revenue. A suggested month with revenue is a hint for a separate query; it does not change the requested window.

Important limitations:

• AI cost comes from Ternary's own AI classification of each billing row, not from service names or tags
• Revenue comes from the Revenue field of a bring-your-own-data (BYOD) import
• A per-label ratio also needs a billing rule that assigns the Custom Label to your revenue rows
• When revenue is missing for the window or not tagged with the label, the tool returns AI cost alone and names what is missing instead of estimating a ratio
• One Custom Label per question

Search and fetch

search

Finds supported Ternary content by name for clients that require the MCP search/fetch contract.

Current search content includes tenants, saved reports and dashboards.

This tool is especially relevant to ChatGPT Deep research.

Search matches accessible tenant names and scans report and dashboard names in at most ten accessible tenants, returning at most 25 results overall. Check the response notes for skipped tenants or sources before concluding that a missing result does not exist. Search matches names; it is not an exhaustive search of billing data.

Reads / writes: reads.

---

fetch

Retrieves a result returned by search.

Depending on the result, it can retrieve:

• Tenant summary information
• Report data rows

ChatGPT Deep research can use search and fetch, but not the full Ternary domain tool set.

A fetched report can contain only a bounded prefix of its rows. Check truncation and continuation information before treating it as the complete report. The fetch tool has no row-pagination input; in clients with the full Ternary tool set, use ternary_get_report_data when you need to page through saved report data. ChatGPT Deep research cannot page through the remaining rows with fetch.

Reads / writes: reads.

Write behavior

All tools above read Ternary data except:

ternary_create_report

Creating a report should happen only after an explicit user request to save an analysis.