FinOps Tools

CoreStack FinOps MCP tools give AI agents structured, authenticated access to cloud cost management data. The tools cover eight functional areas: cloud account discovery, billing trends, anomaly detection, budgets, cost optimization recommendations, Reserved Instance management, savings summaries, and dimension discovery.

All tools require a valid CoreStack session (injected via Context) and return a standard envelope:

{
  "summary" | "Summary": { "total_records": int, ... },
  "output"  | "Output":  list | dict
}

Accounts

get_service_account_ids

Retrieve cloud service accounts (cloud accounts) with their IDs and display names for one or more tenants. Returns the flat ids list used as input to all cost and usage tools. Include native_details in include_fields to determine the cloud provider (AWS, Azure, GCP, OCI) from native_details.type.

Returns: Object containing service_accounts (list of account objects), ids (flat list of account ID strings), total, batch_size, and batch_offset.

Sample Questions

• "List all cloud accounts for tenant abc123."
• "Which cloud provider does account xyz789 belong to?"
• "Show me all active AWS and Azure accounts across my tenants."
• "How many cloud accounts do I have in total?"

Anomalies

get_anomalies

Detect and summarize billing cost anomalies within a date range. Aggregates results by anomaly type, product category, resource category, and impacted accounts. Defaults to the current calendar month when no dates are supplied.

Returns: Object with period, total anomaly count, total cost impact, breakdowns by type / product category / resource category, top impacted accounts, top individual anomalies, and a daily trend series.

Sample Questions

• "Are there any active cost anomalies this month?"
• "What is the total cost impact of anomalies in the last 30 days?"
• "Which AWS accounts have the most anomalies?"
• "Show me anomalies in the Compute category for Azure this quarter."
• "How has the daily anomaly trend looked over the past two weeks?"

get_anomaly_resources

Drill down to resource-level anomaly details. Returns the top resources by cost impact and a breakdown by product category. Use after get_anomalies to investigate specific services or categories.

Returns: Object with period, total count of resources with anomalies, top resource list (sorted by cost impact), and a by-product-category breakdown.

Sample Questions

• "Which specific resources are causing the most cost anomalies this month?"
• "Show me the top 5 anomalous resources in the Storage category on GCP."
• "Which EC2 instances have anomalous spend in account abc123?"

Billing

get_cost_aggregation_trend

Low-level, fully parameterized billing query tool. Supports arbitrary dimension grouping, filter trees, and multiple granularities. Default behavior (no group_by) returns a cloud-account-wise cost breakdown. Use this tool when other higher-level tools do not meet the query requirements.

Returns: Object with total_records summary and raw output list of trend data points.

Sample Questions

• "What is my total AWS spend per month for the last 6 months?"
• "Break down costs by service name for account abc123 in October 2025."
• "Show me daily cost trend for GCP over the past 30 days grouped by region."
• "What is the forecasted spend for my Azure accounts this month?"
• "Filter costs to only show Compute resources grouped by resource category."

get_billing_usage_trend

Retrieve resource consumption trends over time (GB transferred, vCPU-hours, API calls, etc.). Returns time-series usage quantities — not dollar costs. Use alongside get_billing_rate_trend to understand unit economics.

Returns: Object with total_records summary and output list of usage trend data points.

Sample Questions

• "How much storage (GB) did we consume on S3 last month?"
• "Show me daily API call volume for Azure Functions over the past two weeks."
• "Which region consumed the most compute hours in Q3?"
• "Compare monthly data transfer usage across all GCP accounts."

get_billing_rate_trend

Retrieve unit-price trends over time ($/GB, $/hour, $/API call, etc.). Rates are undefined (returned as null) when usage is zero for a period. Use to detect pricing changes or negotiate better rates.

Returns: Object with total_records, undefined_rate_count summary, and output list of rate trend data points.

Sample Questions

• "How has the per-GB S3 storage rate changed over the past year?"
• "Show the hourly EC2 rate trend for account abc123 in us-east-1."
• "Has our Azure compute unit price gone up or down over the last 6 months?"
• "Compare storage rates across AWS and GCP accounts this quarter."

Budget

get_budgets

List all budgets with an aggregated health summary. Calculates spend-vs-budget percentages, identifies over-budget and forecast-exceeded items, and provides breakdowns by scope, frequency, and status.

Returns: Object containing a summary (total budget amount, total actual spend, exceeded count, forecast exceeded count, health percentage, breakdowns by scope/frequency/status, top-10 exceeded budgets) and an output.budgets_list (populated when view="list").

Sample Questions

• "How many budgets are currently over their limit?"
• "What is the overall budget health percentage across all cloud accounts?"
• "Show me all monthly AWS budgets that are in progress."
• "Which budgets are forecast to be exceeded this quarter?"
• "Give me a summary count of budgets by status."

get_budget_detail

Retrieve detailed configuration and spend metrics for a single budget. Fetches thresholds, alert configurations, and optional period-by-period spend history. Uses a fail-open design — partial data is returned if auxiliary calls (alerts, history) fail.

Returns: Object with budget name, ID, frequency, status, currency, scope (type, clouds, accounts), amount details (total, type, growth percentage, planned limits), thresholds, alerts, period (start, end, is_recurring), and optionally spend history.

Sample Questions

• "Show me the full details of budget budget_abc123."
• "What are the alert thresholds configured for this budget?"
• "Has budget xyz been exceeded in previous months? Show the history."
• "What cloud accounts are in scope for budget budget_001?"

Cost Recommendation

get_cost_optimization_by_types

Fetch cost optimization recommendations grouped by optimization type (e.g. idle, orphaned, right-size). Returns estimated monthly savings per resource across all cloud accounts.

Returns: data list where each item contains cost_savings, optimization_type, cloud_account, cloud_provider, region, resource_name, resource_type, resource_id, resource_category, and optimization_name.

Sample Questions

• "What are my top cost optimization opportunities across all cloud accounts?"
• "How much could I save by eliminating idle resources on AWS?"
• "Show me all orphaned Storage resources with potential savings."
• "What is the total potential monthly saving from right-sizing recommendations?"

get_right_sizing_recommendations

Fetch detailed right-sizing recommendations for a specific cloud account. Returns per-resource current and recommended SKU with estimated savings. Use get_service_account_ids to obtain cloud_account_id.

Returns: Object with total_count and recommendation_data list. Each item contains resource_id, resource_name, current_sku, recommended_sku, optimization_type, potential_est_cost_saving, region, cloud_provider, and resource_type.

Sample Questions

• "Which EC2 instances in account abc123 should be right-sized?"
• "Show me the top 10 most impactful right-sizing recommendations for my AWS account."
• "What SKU is recommended for instance i-0abc123?"
• "How much can I save by right-sizing all high-impact resources?"

get_recommendation_resources

Retrieve resource-level details for a specific optimization recommendation type (idle, orphaned, right-size, or config). Use as a drill-down after get_cost_optimization_by_types.

Returns: Object with request_type, cloud_account_id, total_resources, total_pages, page_savings, resources_on_page, and resources list (sorted by estimated saving descending). Each resource includes resource_id, resource_name, resource_type, current_sku, recommended_sku, estimated_cost_saving, region, impact_level, optimization_type, status, and summary.

Sample Questions

• "List all idle resources in my AWS account abc123."
• "Which orphaned disks can I delete to save money on Azure?"
• "Show me open right-sizing opportunities sorted by highest savings."
• "How many resources have been closed or rejected in account xyz?"

Discovery

get_dimensions

Retrieve cost dimensions available for grouping and filtering FinOps queries. Use the returned dimension IDs and names as valid inputs to group_by and filters parameters in billing tools.

Returns: Object with total_dimensions, dimensions_returned, by_type (map of dimension type → list of dimension objects), and dimensions (flat list). Each dimension item contains id, name, type, owner, active, anomaly_detection, and description.

Sample Questions

• "What dimensions are available for grouping my cost data?"
• "Is there a dimension for tagging by team or department?"
• "Show me all dimensions that support anomaly detection."
• "What dimension ID should I use to group costs by environment?"

Reserved Instances (RI)

get_ri_recommendations

Get Reserved Instance purchase recommendations based on historical usage patterns. Helps identify where committing to reserved capacity would reduce costs versus on-demand pricing.

Returns: Object with total_records summary and output containing the list of RI purchase recommendations.

Sample Questions

• "What Reserved Instances should I buy for my AWS workloads?"
• "Show me 3-year RI recommendations with all-upfront payment for Azure."
• "How much can I save by purchasing RIs for my EC2 fleet?"
• "Give me RI recommendations for both AWS and GCP."

get_ri_reservations

List existing Reserved Instance reservations for a given time period. Returns reservation IDs that can be passed to get_ri_reservation_coverage and get_ri_reservation_utilization.

Returns: Object with total_records summary and output containing the list of reservations with their IDs and basic details.

Sample Questions

• "List all my AWS Reserved Instances for the current month."
• "How many Azure reservations do I have active right now?"
• "Show me all reservations across all cloud providers this month."

get_ri_reservation_coverage

Get coverage metrics for a specific Reserved Instance — the percentage of eligible on-demand usage that is being covered by the reservation.

Returns: Object with cloud_account_id, reservation_id, date_filter, and output containing the coverage details from the API.

Sample Questions

• "What is the coverage rate for reservation 191a4aef-… this month?"
• "How well is my EC2 Reserved Instance covering actual usage over the last 3 months?"
• "Is my Azure reservation covering enough of my VM usage year-to-date?"

get_ri_reservation_utilization

Get utilization metrics for a specific Reserved Instance — how much of the purchased reserved capacity is actually being used. Low utilization means paying for unused capacity.

Returns: Object with cloud_account_id, reservation_id, date_filter, and output containing the utilization details from the API.

Sample Questions

• "What is the utilization rate for my EC2 RI 191a4aef-… this month?"
• "Are any of my Reserved Instances significantly under-utilized?"
• "Show utilization for reservation abc-xyz over the last 6 months."
• "Which reservations should I consider selling on the marketplace due to low utilization?"

Savings

get_savings_summary

Combined savings overview that aggregates RI recommendation data and cost-saved-to-date metrics in a single call. Runs two data fetches in parallel (fail-open): potential savings from RI recommendations, and actual savings realized to date.

Returns: Object with recommendations_count, potential_savings, total_reservations, cost_saved_till_date, cost_saved_current_month, potential_recommended, by_cloud (per-provider breakdown), and currency.

Sample Questions

• "How much have we saved through cost optimization recommendations so far?"
• "What is our total potential saving from RI purchases across all clouds?"
• "Show me the savings breakdown by cloud provider."
• "How much did we save this month versus the total savings to date?"
• "What is the potential saving if I switch to 3-year All-Upfront reservations?"