doit-mcp-reporting

DoiT MCP Reporting

Generate report answers through DoiT in the smallest reliable sequence. Prefer existing reports when they already answer the request.

Tool Selection

Use MCP tools as the primary interface for all reporting operations.

Ava Fallback (Ask Ava)

If an MCP tool call fails, returns an error, returns empty/unexpected results, or does not answer the user's question, fall back to Ava — DoiT's AI assistant that can answer any cloud cost question.

Ava can be reached via both the DCI CLI and MCP. Prefer the DCI CLI (dci ask-ava-sync) because it returns cleaner JSON output. Before calling Ava, check if the DCI CLI is installed by running command -v dci. If it is not installed, you MUST ask the user if they want to install it: "To get a better answer, I can ask Ava (DoiT's AI assistant). The recommended way is via the DCI CLI. Would you like to install it? (brew install doitintl/dci-cli/dci)". If the user agrees, invoke the doit-mcp-setup skill to install and authenticate the DCI CLI, then call Ava. If the user declines, fall back to the MCP Ava tool instead.

When to use Ava fallback:

• An MCP tool call fails or times out
• Query results are empty and you cannot determine why
• The user's question is broad, ambiguous, or does not map cleanly to a specific MCP tool
• You need contextual or explanatory information that structured tools cannot provide

How to call Ava:

dci ask-ava-sync ephemeral: true, question: "<rephrase the user's question or describe what you need>" --output json

• Always set ephemeral: true to avoid persisting throwaway conversations.
• Rephrase the question to include relevant context (e.g., time range, service, project) extracted from earlier steps.
• Parse the answer field from the JSON response and present it to the user.

Reference Files

Read these as needed when building queries:

• references/dimensions.md — all dimension IDs (datetime, fixed, label, kubernetes, attribution). Read this when choosing rows, cols, or filters for a query.
• references/metrics-and-options.md — metric types, aggregators, time intervals, data sources, filter operators. Read this when configuring query options.
• references/query-examples.md — common query patterns with ready-to-use field combinations. Read this before building an ad hoc query to see if a pattern already fits.
• templates/report-output.md — output template for presenting results. Copy and fill in when formatting the final report.
• references/dci-cli.md — DCI CLI command reference. Read this only when using the Ava fallback via dci ask-ava-sync.

Core Tool Order

Use these DoiT MCP tools in this order when applicable:

1. validate_user
2. list_reports or list_dimensions
3. get_report_results or run_query

Skip only the steps that are clearly unnecessary.

Session Start

• Call validate_user first when the request depends on account access, tenant identity, or you need to confirm the MCP session is scoped correctly.
• If the user already provided enough context and the session is clearly valid, you may skip validate_user.

Existing Report Workflow

Use this when the user mentions a saved report, dashboard-style output, or a named report such as monthly cost overview.

1. Call list_reports.
2. Match by exact name first, then by obvious close match.
3. If multiple reports are plausible, ask one short clarifying question instead of choosing arbitrarily.
4. Call get_report_results only after you identify the target report.

Prefer this path over run_query when a saved report already exists.

Ad Hoc Query Workflow

Use this when the user wants a slice that is unlikely to map to a saved report.

1. Call list_dimensions if the requested grouping or filter fields are unclear.
2. Build the narrowest possible query — see references/query-examples.md for starting patterns.
3. Call run_query.
4. If the first query is too broad, refine and rerun instead of returning a noisy dump.

Do not call list_dimensions for dimensions you already know from the request.

Output Rules

• Format results using the template in templates/report-output.md.
• Include the time window, grouping, and metric assumptions you used.
• Call out when the answer comes from a saved report versus an ad hoc query.
• If the user asks for top-N output, sort and trim before presenting it.
• If the MCP result is incomplete or ambiguous, say what is missing and ask one focused follow-up.

Gotchas

• Saved reports first: Always check list_reports before building an ad hoc query. Many common requests already have saved reports — running a fresh query wastes time and may produce slightly different numbers due to config differences.
• Dimension IDs are prefixed: Use fixed:service_description, not service_description. The prefix is required. See references/dimensions.md for the full list.
• Label dimensions are base64-encoded: Custom labels use the format label:{base64_key}. Call list_dimensions to discover the actual encoded IDs rather than guessing.
• Data source matters: The default is billing. Switching to bqlens, kubernetes-utilization, or billing-datahub changes the available dimensions and the numbers. Only switch when the user specifically asks for BQ Lens, K8s, or DataHub data.
• Metric 0 is cost: The metric field is a numeric enum, not a string. 0 = cost, 1 = usage, 2 = savings. Using the wrong number silently returns different data.
• Time interval vs. time range: timeInterval controls the column granularity (day, month, etc.). The time range (last 30 days, last quarter) is a separate field. Setting daily interval on a year-long range produces a massive result set.
• Credits can change totals: includeCredits defaults may vary. If the user's numbers don't match expectations, check whether credits are included or excluded.
• Currency context: Results are in the customer's configured currency. If comparing across customers or quoting absolute numbers, note the currency.
• Empty results are valid: A query that returns zero rows may mean the filter is too narrow or the dimension doesn't apply to the selected platform — not that something is broken.

Anti-Patterns

• Do not call run_query before deciding whether a saved report already exists.
• Do not enumerate every available report when the user asked for one report.
• Do not use anomaly tools for generic reporting unless the user explicitly asked about anomalies.
• Do not expose raw JSON unless the user asked for raw output.
• Do not build queries with more than 3 row dimensions — the result set becomes unreadable. Narrow with filters instead.
• Do not guess dimension IDs for labels or attributions — always call list_dimensions to discover them.