amg-check-azure-spend

Runtime Context

• Current UTC time: !date -u +%Y-%m-%dT%H:%M:%SZ
• Config: !cat memory/amg-check-azure-spend/config.md 2>/dev/null || echo "NOT_CONFIGURED"
• Arguments: subscription-ids=$ARGUMENTS

Azure Subscription Cost Analysis

Analyze Azure subscription costs for the last full billing month using amgmcp_cost_analysis. Queries each subscription individually with mandatory waits between calls to respect the billing API rate limit.

Critical Constraints

• No subagents for MCP. The Agent tool cannot access MCP tools — all MCP calls must be made from the main context.
• Sequential queries only. Query one subscription at a time. Never query multiple subscriptions in parallel.
• Mandatory 1-minute wait. After each amgmcp_cost_analysis call, run sleep 60 via Bash before the next call. This is non-negotiable — the billing API has a tight rate limit.
• Recommend 5 subscriptions per run. The billing API has tight throttling — each subscription takes 1-3 minutes (wait time + potential 429 retries). Warn the user if they select more than 5 that the run will be slow, but allow it if they confirm.
• 429 backoff. If you receive a 429 (Too Many Requests), wait 2 minutes (sleep 120), then retry. If 429 persists, wait 5 minutes (sleep 300) and retry once more. If still failing, skip that subscription and note it in the report.

Progress Tracking

Update checkboxes as you complete each phase:

• Phase 1a: Datasource validated
• Phase 1b: Subscriptions listed
• Phase 1c: Subscriptions selected
• Phase 2: Cost queries completed (0/N)
• Report presented
• Report saved to memory/amg-check-azure-spend/report.md

Configuration

If Config shows NOT_CONFIGURED: Run First-Run Setup at the bottom of this file, then return here.

If Config is populated: Extract the datasource UID from the pre-loaded Runtime Context above.

• Datasource UID: from ## Azure Monitor Datasource > UID

Time Range

Always use the last full billing month boundaries. Compute them from the "Current UTC time" in the Runtime Context above:

• startTime: first day of the previous month at 00:00:00.000Z (e.g., if current UTC time is 2026-04-16T..., startTime = 2026-03-01T00:00:00.000Z)
• endTime: first day of the current month at 00:00:00.000Z (e.g., if current UTC time is 2026-04-16T..., endTime = 2026-04-01T00:00:00.000Z)

Do NOT use relative expressions like now-30d — billing months have variable lengths.

---

Workflow

Phase 1a: Validate Datasource

Call amgmcp_datasource_list (no parameters). Find entry with type == "grafana-azure-monitor-datasource".

• Matches configured UID -> proceed.
• Different UID -> update memory/amg-check-azure-spend/config.md, warn user, use new UID.
• Not found -> abort with error.

Phase 1b: List All Subscriptions

Call amgmcp_query_azure_subscriptions with the validated datasource UID.

Present the full list as a table:

#	Subscription Name	Subscription ID
1	...	...

Phase 1c: Select Subscriptions

If $ARGUMENTS provides subscription IDs (comma-separated): Use those directly. Validate they appear in the Phase 1b list.

If 5 or fewer subscriptions exist: Use all of them.

If more than 5 subscriptions exist: Present the list to the user and ask them to choose. Suggest a default selection of ~5 based on name (e.g., production subscriptions first). Example prompt:

"Found N subscriptions. I recommend selecting around 5 — the billing API has tight rate limits, so each subscription takes 1-3 minutes (mandatory waits + potential 429 retries). You can select more, but the run will be slow. Which subscription numbers would you like to analyze? (e.g., 1,3,5) Or press Enter to use my suggested selection: [list]."

If the user selects more than 5: Warn them about the expected duration (roughly 2-3 minutes per subscription due to mandatory waits and 429 backoffs), then proceed if they confirm.

Phase 2: Query Cost for Each Subscription

For each selected subscription, one at a time:

1. Call amgmcp_cost_analysis with:

   azureMonitorDatasourceUid: {DATASOURCE_UID}
   subscriptionId: {SUBSCRIPTION_ID}
   startTime: {BILLING_MONTH_START}
   endTime: {BILLING_MONTH_END}
   

2. Record the cost breakdown from the response:

   • Total cost for the subscription
   • Top cost drivers by resource type (MeterCategory)
   • Cost by region
   • Any notable cost spikes or anomalies

3. Wait 1 minute before the next query:

   sleep 60
   

4. If you receive a 429 (Too Many Requests):

   • Wait 2 minutes: sleep 120
   • Retry the same subscription
   • If 429 again, wait 5 minutes: sleep 300 and retry once more
   • If still 429, skip this subscription and note "Rate-limited — skipped" in the report

Repeat for each subscription. Do NOT proceed to the next subscription without the 1-minute wait.

---

Output Format

Present a cost report with these sections:

1. Billing Period

State the exact billing month analyzed (e.g., "March 2026: 2026-03-01 to 2026-04-01").

2. Cost Summary Table

Subscription	Total Cost	Top Resource Type	Top Region	Status
sub-name-1	$X,XXX.XX	Virtual Machines	East US	OK
sub-name-2	$X,XXX.XX	Storage	West US 2	OK

3. Per-Subscription Breakdown

For each subscription:

• Total cost for the billing month
• Top 10 cost drivers by MeterCategory (resource type) with amounts and percentages
• Cost by region — table showing spend per Azure region
• Notable observations — any unusually high costs, unexpected resource types, or potential optimization opportunities

4. Cross-Subscription Comparison

• Which subscription has the highest spend
• Common cost drivers across subscriptions
• Regional distribution of spend across all queried subscriptions

5. Cost Optimization Suggestions

Based on the data, flag:

• Subscriptions with disproportionately high costs in a single category
• Resource types that dominate spend (potential right-sizing candidates)
• Regions with unexpectedly high costs

---

Save Report

After presenting findings, save the report to memory/amg-check-azure-spend/report.md:

1. Read the current file (if it exists).
2. Overwrite with the full cost report from this run, including:
   • Billing period and generation date
   • Cost summary table across all queried subscriptions
   • Per-subscription breakdowns (top services, regions, resource types)
   • Cross-subscription comparison
   • Cost optimization suggestions
   • Any skipped subscriptions (rate-limited) noted with reason
3. Update the "Generated" date header to today's date.

This file provides a baseline for future runs to compare month-over-month trends.

---

Error Handling

See ${CLAUDE_SKILL_DIR}/reference/error-handling.md for the full recovery table.

---

First-Run Setup

Run only when Config shows NOT_CONFIGURED. After completing, return to the Workflow above.

1. Discover Datasource UID: Call amgmcp_datasource_list. Filter type == "grafana-azure-monitor-datasource". Prefer uid == "azure-monitor-oob" if multiple match. Abort if zero match.

2. Write config: Write memory/amg-check-azure-spend/config.md:

# amg-check-azure-spend Configuration

User-specific values for the Azure spend analysis skill.
This file is auto-generated on first run and can be edited manually.

## Azure Monitor Datasource
- **UID**: {discovered_uid}
- **Name**: {discovered_name}

3. Confirm: Show the resolved config and ask for confirmation before proceeding.