preview_virtual_dimension_draft
Preview per-rule costs or a groupBy breakdown (read-only BigQuery). virtualDimensionId in inputs equals id from list/get/search. Use when the user wants to validate draft or published rule costs before publishing. Operates on the latest pending draft if one exists (draftPersisted: true); otherwise previews published rules in memory without creating a draft (draftPersisted: false — not publishable). To publish changes after editing published-only state, call update_virtual_dimension_draft for an existing virtualDimensionId (or create_virtual_dimension_draft for a brand-new VDIM) — preview alone does not persist. Call after a successful create/update. Read the "summary" field first. Both modes share the same time window: optional datePreset (official presets — TRAILING_30_DAYS default, same enum as dashboards) or explicit from/to (YYYY-MM-DD, same shape as query); mutually exclusive. mode "costs": per-rule costs with totals.namedRulesSharePercent / totals.leftoverSharePercent, each rule's conditionCel and allocatesTo, plus howToRead. mode "breakdown": spend inside a target rule (ruleId or ruleIndex) split by groupBy — returns period (datePreset or from/to), scope.explanation, topValues[{ value, cost, percentOfScope }], and dailyTotals (not raw chart JSON). Discover valid groupBy values via search with type: ["dimensions"]. position (from get and preview costs output) and ruleIndex (preview/overlap input) refer to the same 0-based ordinal in the ordered rule list [...rules, leftover]. Use ruleId; ruleIndex identifies the same rule by 0-based position. Target leftover via ruleId of leftoverRule or ruleIndex: rules.length. Optional currency (default USD) — pass the same value as query cost queries to align totals. costMetric selects the cost column (default cost); valid ids: cost, effective_cost, list_cost, contracted_cost (also accepts contracted_costs), unblended_cost, net_unblended_cost, amortized_cost, net_amortized_cost.
EXAMPLES:
• "Preview Environment VDIM draft costs" → { virtualDimensionId: "<virtualDimensionId from create/list>", mode: "costs" }
• "What cos_region values sit inside Production?" → { virtualDimensionId: "<virtualDimensionId from create/list>", mode: "breakdown", ruleId: "<from get/preview costs>", groupBy: "cos_region", datePreset: "TRAILING_30_DAYS" }
• "Preview costs in EUR to match earlier queries" → { virtualDimensionId: "<virtualDimensionId from create/list>", mode: "costs", currency: "EUR", from: "2025-01-01", to: "2025-03-31" }
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"virtualDimensionId": "<virtualDimensionId>",
"mode": "<mode>",
"context": "<context>"
},
"name": "preview_virtual_dimension_draft"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Explicit window end (YYYY-MM-DD). Use with from instead of datePreset — same shape as query. | |
| from | No | Explicit window start (YYYY-MM-DD). Use with to instead of datePreset — same shape as query. | |
| mode | Yes | `costs` (per-rule costs including leftover and rule metadata) or `breakdown` (drill into a rule). | |
| slug | No | Organization slug. Omit to auto-detect from your account (fails if you belong to multiple orgs). | |
| ruleId | No | Target rule id (breakdown mode). Use this instead of ruleIndex. | |
| context | Yes | A few words on why you are calling this tool, for the server developer's analytics. Describe people and things by role, such as "a customer". Do not quote the user or include names, emails, or other personal details. | |
| groupBy | No | Dimension to split by (breakdown mode) | |
| currency | No | Cost currency (default USD). Pass the same currency as prior query calls to align preview totals. | |
| llm_model | No | The model identifier you are running as, for example "claude-opus-4-8" or "gpt-5.2". Pass "unknown" if you are not certain. Recorded for the server developer's analytics. | |
| ruleIndex | No | Target rule index (breakdown mode fallback) | |
| costMetric | No | Cost column id (default cost). Valid: cost, effective_cost, list_cost, contracted_cost, unblended_cost, net_unblended_cost, amortized_cost, net_amortized_cost (also accepts contracted_costs → contracted_cost). | |
| datePreset | No | Official date preset (same values as dashboards/query context). Default TRAILING_30_DAYS. Mutually exclusive with from/to. | |
| conversation_id | No | The conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics. | |
| virtualDimensionId | Yes | Virtual dimension id (stable public identifier) |