Azure Cost Calculator

Deterministic Azure cost estimation using the public Retail Prices API. Never guess prices — always query the live API via the scripts.

Runtime Detection

Choose the script runtime based on what is available:

Both produce identical JSON output. Bash flags use --kebab-case equivalents of PowerShell -PascalCase parameters (e.g., -ServiceName → --service-name).

Declarative Parameters

Service reference files specify query parameters as Key: Value pairs. To execute a query, translate each parameter to the detected runtime's syntax:

• •Bash: --kebab-case flags (e.g., ServiceName: Virtual Machines → --service-name 'Virtual Machines')
• •PowerShell: -PascalCase flags (e.g., ServiceName: Virtual Machines → -ServiceName 'Virtual Machines')

String values with spaces require quoting when passed to scripts. Numeric values (Quantity, InstanceCount) do not.

Workflow

Phase 1 — Analysis (no API queries)

1. •

   Parse — extract resource types, quantities, and sizing from user's architecture

2. •

   Locate each service reference: a. File search — search for files matching references/services/**/*<keyword>*.md b. Category browse — if search returns 0 or ambiguous results, read the category index in references/shared.md c. Broad search — list or search references/services/**/*.md to see all available files d. Discovery — if no file exists, use the explore script to find the service in the API

3. •

   Read matched service files; check billingNeeds and follow dependency chains (e.g., AKS → VMs → Managed Disks)

4. •

   Classify each parameter using the Disambiguation Protocol in shared.md:

   • •Specified — user provided value (use verbatim)
   • •Never-assume gap — required parameter missing (must ask)
   • •Safe-default gap — optional parameter missing (use default, disclose)
5. •

   Specification Review — present a summary:

   Service	Specified	Missing (will ask)	Defaults (will assume)

   • •If any never-assume parameter is missing → ask user before proceeding
   • •If only safe-default gaps remain → disclose defaults and proceed to Phase 2
   • •Single-service shortcut: skip this table for single-service estimates where all parameters are specified

Phase 2 — Estimation

1. •Query — run the pricing script for each service using parameters from service files + user input + resolved defaults
2. •Calculate — apply cost formulas from service files; multiply by quantities
3. •Present — output the estimate with:
   • •Assumptions block (see Disambiguation Protocol in shared.md) — listed before cost numbers
   • •Line items: service, unit price, quantity/hours, monthly cost
   • •Grand total: re-sum all line-item monthly costs independently; if discrepancy, use re-summed value

Post-Estimate Iteration

After presenting the estimate, the user may request changes (switch region, add RI, resize instances, add/remove services). Re-run only the affected queries — do not restart the full workflow.

Reference Index (load on demand)

Critical Rules

1. •Never guess prices — always run the script against the live API
2. •Infer currency and region from user context — if unspecified, ask the user or default to USD and eastus
3. •Ask before assuming — if a required parameter is ambiguous or missing (tier, SKU, quantity, currency, node count, traffic volume), stop and ask the user
4. •Default output format is Json — never use Summary (invisible to agents)
5. •Lazy-load service references — only read files from references/services/ directly required by the user's query. Use the file-search workflow (Step 2) to locate specific files.
6. •PowerShell: use pwsh -File, not pwsh -Command — on Linux/macOS, bash strips OData quotes from inline commands
7. •Use consistent output categories — group line items by category directory names from references/services/ (compute, databases, networking, etc.)
8. •Scope to user-specified resources — only include resources explicitly stated in the user's architecture. Companion resources from billingNeeds are included automatically.

Service File Metadata

YAML front matter fields. Optional fields use default elision — omitted means the default applies.

Universal Traps

These apply to EVERY query:

1. •serviceName and all filter values are case-sensitive — use exact values from service reference files
2. •Unfiltered queries return mixed SKU variants — always filter with productName/skuName to the specific variant needed
3. •Multi-meter resources need separate queries — run one query per meter with -MeterName

Batch Estimation Mode

When estimating 3 or more services, use these rules to reduce token consumption:

1. •Partial reads — read only lines 1–45 of each service file (YAML front matter, trap, first query pattern).
2. •Front matter routing — use YAML metadata to skip unnecessary work:
   • •hasMeters: false / pricingRegion: api-unavailable → skip API; use Known Rates or primaryCost
   • •pricingRegion: global → Region: Global; empty-region → omit region
   • •apiServiceName → use instead of serviceName in queries
   • •hasFreeGrant: true → apply grant deduction; privateEndpoint: true → add PE line item
3. •Full read triggers — no query pattern in partial read, non-default config, 0/unexpected results, or billingConsiderations applies.
4. •Parallel queries — run independent service queries in parallel.
5. •Skip redundant references — read shared.md and pitfalls.md once at the start, not between services.
6. •Progressive distillation — after each service query returns, emit a summary row before proceeding: | Category | Service | Resource | Unit Price | Unit | Qty | Monthly Cost | Notes | Multi-meter services get one row per line item. After all queries complete, assemble the final estimate from the accumulated rows. Do not re-read service files already distilled unless a full read trigger is needed. During Post-Estimate Iteration, replace the distillation row(s) for any re-queried service.