/finops-toolkit

name: finops-toolkit
description: This skill should be used when the user asks about "FinOps hubs", "FinOps toolkit", "KQL queries", "Kusto", "cost data analysis", "Hub database", "Costs function", "Prices function", "Recommendations function", "FinOps hubs deployment", "Azure Data Explorer", "ADX cluster", or any FinOps hubs operations.
license: MIT
compatibility: Requires Azure MCP Server and Azure CLI authentication. For queries, requires Database Viewer access to FinOps hub ADX cluster.
metadata:
  author: microsoft
  version: "1.0"

FinOps Toolkit

FinOps hubs are a scalable platform for cloud cost analytics, insights, and optimization built on Azure Data Explorer (Kusto) or Microsoft Fabric RTI. This skill covers KQL-based cost analysis and hub infrastructure deployment.

Task routing

Load only the references relevant to the task at hand.

> **Maintainer note:** The references in this table intentionally use **shorthand skill paths** for readability. They are **not** a claim that the plugin contains literal `toolkit/...`, `focus/...`, or bare `.kql` files next to `SKILL.md`. > > The `Build-AgentPlugin.ps1` packaging hook copies `src/queries` and `docs-mslearn` into this skill's `references/queries` and `references/docs-mslearn` directories. Resolve the shorthand in this table as follows: > > - `toolkit/...` → `references/docs-mslearn/toolkit/...` > - `focus/...` → `references/docs-mslearn/focus/...` > - bare `.kql` names → `references/queries/catalog/...` > - `references/...` paths are already literal >

| Task | Load these references first | |------|-----------------------------| | Write or run a KQL query | `references/finops-hubs.md`, `references/queries/finops-hub-database-guide.md` | | Use a pre-built query | `references/queries/INDEX.md`, then the specific `.kql` file | | Deploy a new hub | `references/finops-hubs-deployment.md`, `toolkit/hubs/deploy.md`, `toolkit/hubs/template.md` | | Upgrade a hub | `references/finops-hubs-deployment.md`, `toolkit/hubs/upgrade.md`, `toolkit/hubs/compatibility.md` | | Savings / ESR analysis | `toolkit/hubs/savings-calculations.md`, `savings-summary-report.kql`, `commitment-discount-utilization.kql` | | Reservation recommendations | `reservation-recommendation-breakdown.kql`, `toolkit/hubs/savings-calculations.md` | | FOCUS columns / mapping | `focus/what-is-focus.md`, `focus/mapping.md` | | Power BI setup | `toolkit/power-bi/setup.md`, `toolkit/power-bi/connector.md` | | Troubleshooting / errors | `toolkit/help/troubleshooting.md`, `toolkit/help/errors.md` | | PowerShell commands | `toolkit/powershell/powershell-commands.md` + the specific command file | | Connect to hub for first time | `/ftk/hubs-connect`, `references/settings-format.md` | | Check hub health / version | `/ftk/hubs-health-check`, `toolkit/hubs/compatibility.md` |

Database functions

The Hub database exposes four analytic functions. Always use the `Hub` database — never `Ingestion`.

| Function | Purpose | Key columns | |----------|---------|-------------| | `Costs()` | Cost and usage analytics (FOCUS-aligned) | `BilledCost`, `EffectiveCost`, `ContractedCost`, `ListCost`, `ServiceName`, `ResourceName`, `Tags` | | `Prices()` | Price sheets with list, contracted, and effective pricing | `ListUnitPrice`, `ContractedUnitPrice`, `x_EffectiveUnitPrice`, `PricingUnit` | | `Recommendations()` | Reservation and savings plan recommendations | `x_EffectiveCostBefore`, `x_EffectiveCostAfter`, `x_EffectiveCostSavings` | | `Transactions()` | Commitment purchases, refunds, and exchanges | `BilledCost`, `ChargeCategory`, `x_SkuTerm`, `x_TransactionType` |

Columns prefixed with `x_` are toolkit enrichments added during ingestion (e.g., `x_ResourceGroupName`, `x_CommitmentDiscountSavings`, `x_TotalSavings`). Full column definitions: `references/queries/finops-hub-database-guide.md`.

Query execution

• Uses **KQL (Kusto)**, not SQL
• Default analysis window: 30 days
• Always include `tenant` — cross-tenant (B2B) scenarios fail without it
• Always include `subscription` — required by the MCP tool contract

Environment settings are read from `.ftk/environments.local.md` at the project root. Use the `default` environment unless the user specifies one. See `references/settings-format.md` for the file format.

Use the `azure-mcp-server` tool with command `kusto_query` for all live Hub queries.

{
  "cluster-uri": "<cluster-uri from .ftk/environments.local.md>",
  "database": "Hub",
  "tenant": "<tenant from .ftk/environments.local.md>",
  "subscription": "<subscription from .ftk/environments.local.md>",
  "query": "<KQL query>"
}

Required parameters for `kusto_query`: `cluster-uri`, `database`, `tenant`, `subscription`, and `query`.

Query catalog

Check the shipped query catalog before writing custom KQL. Read the `.kql` file, substitute parameters, then execute. See `references/queries/INDEX.md` for the full scenario-to-query matrix.

| Query | Description | |-------|-------------| | [costs-enriched-base.kql](references/queries/catalog/costs-enriched-base.kql) | Base query with full enrichment and savings logic for all cost columns. Use for scoped row-level custom analytics or repeated drill-downs. | | [monthly-cost-trend.kql](references/queries/catalog/monthly-cost-trend.kql) | Total billed and effective cost by month for trend analysis and executive reporting. | | [monthly-cost-change-percentage.kql](references/queries/catalog/monthly-cost-change-percentage.kql) | Month-over-month cost change percentage for both billed and effective costs. | | [top-services-by-cost.kql](references/queries/catalog/top-services-by-cost.kql) | Top N Azure services by cost. Key for cost visibility. | | [top-resource-types-by-cost.kql](references/queries/catalog/top-resource-types-by-cost.kql) | Top N resource types by cost and usage. | | [top-resource-groups-by-cost.kql](references/queries/catalog/top-resource-groups-by-cost.kql) | Top N resource groups by effective cost. | |