budget-setup

name	budget-setup
description	Create a budget with sensible default thresholds, contact emails, and an optional action group. WHEN: "create budget", "setup budget", "need a budget", "no budgets", "budget recommendations". INVOKES: list_budgets, query_costs, forecast_costs, create_budget
license	MIT
metadata	{"version":"1.0.0"}

Budget Setup

Help the user create a budget that reflects expected business demand — not just trailing spend — with a default tiered alert model that fits Azure's notification limits.

Step 1: Check Existing Budgets

Call list_budgets on the scope. If a budget already exists, surface it and ask whether the user wants to update it or add a new one. If the existing budget amount is far below current spend (e.g., $1,000 limit on $4,500 actual), flag it as stale and ask whether the workload grew intentionally.

Step 2: Build a Spend Baseline

Call query_costs with timeframe=TheLastMonth and forecast_costs on the same scope. Present:

• Last month actual — $X
• Current month forecast — $Y
• Trend — growing / stable / declining

forecast_costs returns one row per day, each tagged CostStatus Actual or Forecast, and the same date can appear as both. To get $Y, take one value per date — the Actual if present, otherwise the Forecast — and sum PreTaxCost.

Treat these as a starting point for the recommendation, not the budget amount itself.

Step 3: Confirm Business Context

Ask the user two short questions:

1. Firm spending limit or tracking budget? A firm limit is an amount they intend not to exceed; tracking is visibility only. Either way, an Azure budget only sends alerts — it never stops, throttles, or disables resources when exceeded.
2. Any planned changes this quarter? (new deployments, migrations, reservations, seasonal peaks)

Use the answers to adjust the recommendation:

• No planned changes → base the amount on the forecast, optionally adding a small buffer for organic growth (e.g., ~10%); confirm the buffer with the user rather than applying it silently.
• Planned changes → ask for the rough expected delta and add it to the baseline.
• Firm limit → set the amount at that limit and pick lower thresholds for earlier action.

Step 4: Recommend Scope & Thresholds

Scope (in priority order):

1. Subscription — the default choice for environment-level control.
2. Resource group — for a high-spend workload inside a shared subscription.

create_budget creates budgets at subscription and resource-group scope only. Azure also supports budgets at management-group, department, enrollment-account, and billing-account scope for org-wide governance, but those are created in the Azure portal — recommend a subscription or resource-group budget here, and point the user to the portal if they need a broader scope.

Default threshold model (4 notifications, within Azure's 5-per-budget limit):

Threshold	Type	Purpose
80%	Actual	Early warning — review trajectory
100%	Actual	At limit — act now
80%	Forecasted	Projected to overshoot soon — defer non-critical spend
100%	Forecasted	Projected to exceed limit — escalate

Present these as a starting point and let the user adjust before creating. Some teams prefer tighter thresholds (e.g., 50/80/100 actual); others wider.

Step 5: Create the Budget

Confirm the proposal with the user, including the notification contacts:

Recommended budget:

• Scope: [subscription / RG]
• Amount: $X/month (based on $Y forecast + buffer / planned changes)
• Thresholds: 80% / 100% actual + 80% / 100% forecasted
• Contacts: [emails the user provides]
• Action group (optional): [Action Group resource ID, if the user has one]

Create it?

On confirmation, call create_budget. When you pass notifications, the top-level contactEmails param is ignored, so embed contactEmails inside every notification object — each notification needs at least one contact email or the call fails. create_budget won't overwrite an existing budget: if one of the same name already exists at the scope, the call is refused, so pick a different name (or have the user delete the existing budget first). Then call list_budgets to verify and show the created budget.

Notes

Budgets are a core Cost Management guardrail — but only when they reflect business reality and have the right people on the notification list. A budget without an accountable owner is just a number.