Mavvrik

Get GraphQL type information - T=type,I=input,E=enum,U=union,F=interface;s=String,i=Int,f=Float,b=Boolean,d=ID;@D=deprecated;!=required,[]=list,<>=implements; Hint: ## Schema Discovery This tool reports what the schema actually declares. Field, argument and type names that did not come from it fail at validate or execute — the schema is the only record of what exists. ### Workflow **Step 0 — Session context:** `helloMCP` carries the current date/time for the session; date-sensitive queries depend on it. **Step 1 — Initialize:** Run ONE introspection on the root `Query` type at depth 1. This gives you the full list of available queries and their signatures. **Step 2 — Deep Dive:** For each query you plan to execute, introspect its dependencies: - **Return types:** If it returns an OBJECT, INTERFACE, or UNION → introspect that type to discover selectable fields. - **Input types:** If it takes INPUT_OBJECT arguments (`option`, `filter`, `search`) → introspect to learn its `inputFields`. `Json`-typed fields inside them (`thresholds`, `tags`, `vtags`) are free-form scalars — nothing to introspect. **Step 3 — Mark Required Fields:** Note every field marked "EFFECTIVELY REQUIRED" or ending with `!`. A query omitting one of these fails. ### Key Principles - Introspection results are your ONLY authority on what fields exist and what's required. - Never guess enum values (groupBy, yAxis, etc.) — always derive them from introspecting the relevant enum type. - Results are valid for the entire session, so a type already introspected does not change; a field error is the signal that one needs re-reading. - If a field name or type is ambiguous, introspect again — don't assume.

introspect

List the tenants you're authorized to switch to (for use with the tenant_id parameter on execute/execute_sql/rest_invoke). Root sees all; admins see their children.

list_tenants

Read one Mavvrik REST management resource discovered via rest_search, using structured arguments (no code). GET operations only — this surface cannot create, update or delete. Targets the Mavvrik management API at https://api.mavvrik.ai. Your tenant is applied automatically from your credentials — do NOT put a tenant in `args`. To query a DIFFERENT tenant you are authorized for, pass the optional top-level `tenant_id`. Example: operation="get_tenantId_budget_budgetId", args={"budgetId": "z4ssydfhwq"}.

rest_invoke

Execute a GraphQL operation. Use the `introspect` tool to get information about the GraphQL schema. Always use the schema to create operations - do not try arbitrary operations. If available, first use the `validate` tool to validate operations. DO NOT try to execute introspection queries. Hint: ## Execution Rules **Sequence: helloMCP → introspect → validate → execute.** `helloMCP` supplies the reference date and display currency, `introspect` the field/argument/enum names, and `validate` catches schema errors before a query runs. Field and type names that were not read from `introspect` fail at validate or execute. ### PRE-FLIGHT CHECKLIST — 4 rules `validate` can't catch (they fail only at execute) 1. **Series (`costs`/`aiCosts`/`saasCosts`/`k8sCosts`): pass BOTH `groupBy` and `xAxis`** (never `category`). 2. **`limit`: only `10/20/30/50/100`, or `-1` for all/total** — never `0` or arbitrary ints; always set it (default `20`). REQUIRED for `*TopEntries` AND `costVariances` (no backend default → omitting fails with `Unrecognized name: undefined`). 3. **`options` (cloud/resource): `discount`/`refund`/`tax` + exactly one of `default`/`net`/`amortized`/`net_amortized`** — the baseline is `["default","discount","refund","tax"]`; swap only the variant when the user asks (SaaS / GenAI / agent / code-assist: `[]`; K8s cost / datacenter: `["default"]`). Other strings are silently dropped. 4. **Introspect `Filter` before building one** — it's flat typed fields, no `json` wrapper. ### Two totals that are computed, not read - **Cost-variance net** = (this-period total) − (prior-period total). Summing the per-group deltas is approximate — they are rounded and drop unattributed rows. - **Coverage** is ONE month's row: `Usage Hours` is the covered (ri+sp) hours, not total hours. **STEP 0 — Session context:** `helloMCP` is the source of the current date/time and the tenant's display currency. `helloMCP.datetime` is the reference point for every relative date ("last 7 days", "this month"); the server clock and the tenant's date are not otherwise knowable here. `helloMCP.currency` (e.g. `"USD"`, `"EUR"`) is the currency every cost figure in the session is denominated in, and both values hold for the whole session. `helloMCP` returns `{ name, datetime, currency, settings, tagPolicies }`. It does NOT return default cost `options` — for standard cloud cost + resources use the fixed baseline `["default","discount","refund","tax"]` (variant `default` = actual/blended on-demand, NOT `amortized`); only when the user asks for a different variant, swap the single variant flag per the Cost Variant Selection rule (e.g. `["amortized","discount","refund","tax"]`). There is NO field echoing back which options ran: CostTopEntriesResponse returns only topEntries and total, so the variant a figure used is knowable only from the request that produced it. Also cache `helloMCP.settings` — the tenant's saved defaults, each an array of `{id,name,scope,...}` groups, that feed your `thresholds` (anomaly) and savings-floor inputs: - `settings["cost-anomalies"]` → the tenant's anomaly threshold ALREADY in the canonical GROUPED shape `[{id,name,scope,thresholds:[{type,value,relationship}]}]`. `AnomalyOption.thresholds` is OPTIONAL and the server applies NO default — it filters by EXACTLY what you pass, so omitting it returns EVERY anomaly (sub-dollar noise included). So pass one in almost every case: for "the configured / my usual threshold" (the common case) pass this VERBATIM as `AnomalyOption.thresholds`; to override, keep that exact grouped shape and change only the inner rule values; only OMIT `thresholds` when the user explicitly wants ALL anomalies. NEVER flatten it to `[{type,value}]` (without the wrapping `{id,name,scope,thresholds:[...]}` group the server can't key on it and the filter is dropped). A settings group may carry an `alerts` array; strip it, only `{id,name,scope,thresholds}` is read. - `settings["savings-thresholds"]` → the tenant's savings floor `[{id,name,scope,threshold:<number>}]` — pass it as the `thresholds` for recommendation/savings queries. **Date Resolution Rules:** - Always use the full year from the `helloMCP` response when resolving partial dates. - "February" or "last February" → resolve to the most recent February relative to today (e.g. "2026-02-01" if today is in March 2026). - "last month" → the calendar month immediately before today's month. - "this month" → today's current calendar month. - "this year" / "YTD" → January 1st of today's year through today. - "last year" → full previous calendar year (Jan 1 – Dec 31). - "yesterday" / "today" → exact dates derived from the `helloMCP` timestamp. - Never assume a year. If ambiguous, always default to the current year from `helloMCP`. ### Choosing the Query: ranking vs. series, and the dimension field (READ FIRST for "top N") DEFAULT to `*TopEntries` for any total or ranking over a single whole calendar month: `costTopEntries` (cloud), `aiCostTopEntries` (GenAI), `saasCostTopEntries` (SaaS), `k8sCostTopEntries` (K8s). They take `month` (the month's first day), rank by `category`, and return a ranked `topEntries` list plus the grand `total`. - PERIOD TOTAL (single month) → read `*TopEntries.total` (grand total across ALL groups; the source of truth for the headline and each row's % share). Take it ONLY from `total`; NEVER sum the rows (omits the long tail). KNOWN LIMITATION: `total` excludes the blank/empty-`groupBy` bucket, a small accepted undercount — do NOT sum the `costs` series to "fix" it (the series total is the less trustworthy of the two). - RANKING (single month; "top N", "biggest spender", "most expensive") → `*TopEntries`, rank by `category`, set `limit`. Use the SERIES query (`costs`/`aiCosts`/`saasCosts`/`k8sCosts`) ONLY when `*TopEntries` cannot answer: - Custom/relative range ("last 7 days", "this week", an explicit from/to) → `fromDate`+`toDate`+ `interval` (e.g. "day-7-custom"), `groupBy` the dimension; for a top-N over the range, sum the points per group and rank them yourself. `*TopEntries` has no `fromDate`/`toDate` and CANNOT do ranges. - Pure time-series trend (no ranking) → `xAxis: "date"`. Period comparison (MoM/WoW) → `costVariances`. E.g. "GenAI spend / top 5 models this month" → `aiCostTopEntries`; "top 10 cloud costs … last 7 days" → `costs` (NOT `costTopEntries`, which has no date range). THE DIMENSION FIELD — DO NOT SWAP (the #1 cause of failures). Each family reads the dimension from a DIFFERENT field; the wrong one resolves to `undefined` and fails with `Unrecognized name: undefined` at the DATA LAYER — `validate` passes, `execute` still crashes. NO overlap between the two sets: - SERIES (`costs`/`aiCosts`/`saasCosts`/`k8sCosts`): `groupBy` = the dimension (REQUIRED) + `xAxis:'date'` (REQUIRED, also correct when you'll sum points into per-group totals). NEVER `category` here — it is ignored. - RANKING (`*TopEntries`): `category` = the single dimension (REQUIRED in practice) + always `limit` (no backend default). IGNORES `groupBy`/`xAxis`. Mnemonic: SERIES → `groupBy`+`xAxis:'date'`; RANKING → `category`. To rank a SERIES over a custom range: `groupBy:'product_name'`, `xAxis:'date'`, `interval:'day-30-custom'`, `fromDate`/`toDate`, `limit:100`, `options:[...]`, then sum each group's points and sort descending. ### QUICK ROUTING TABLE (match here FIRST, then read the family bullet for detail) One row per subject. Pick the row, copy its query / Option type / dimension field / `options` array VERBATIM — do not infer. `rank/total` = the `*TopEntries` or summary query (single month); `series` = the range/trend query. | Subject | rank/total query | series query | Option type | dim field | options | |---|---|---|---|---|---| | Cloud cost | costTopEntries | costs | CostOption | category / groupBy | ["default","discount","refund","tax"] | | Resources | resourceTopEntries | resources | ResourceOption | category / groupBy | ["default"] | | SaaS | saasCostTopEntries | saasCosts | CostOption | category / groupBy | [] (provider:"all") | | GenAI cost | aiCostTopEntries | aiCosts | CostOption | category / groupBy | [] | | GenAI insight | aiInsightMetrics | aiInsights | CostOption | groupBy | [] (REQUIRES fromDate+toDate+interval) | | Code-assist (spend) | aiAssistCostTopEntries | aiAssistCosts · aiAssistCostItems | CostOption | category / groupBy | [] | | Code-assist (seats/quota) | — | aiAssistUtilizations · aiAssistUtilizationItems | CostOption | — | [] (fromDate+toDate+interval) | | Agent cost | agentCostTopEntries | agentCosts | CostOption | category / groupBy | [] | | Agent session | agentSessionTotalSummary | — | AgentSessionOption | — | — (fromDate+toDate ~30d) | | Agent anomaly | agentAnomalyTotalSummary | — | AnomalyOption | — | thresholds = helloMCP.settings["agent-anomalies"] | | K8s cost | k8sCostTopEntries | k8sCosts | CostOption | category / groupBy (+yAxis) | ["default"] | | K8s utilization | — | k8sUtilizations | K8sUtilizationOption | — | optional default\|chargeable (fromDate+toDate+interval) | | K8s efficiency | — | k8sEfficiencies | K8sUtilizationOption | — | ["default"] (fromDate+toDate+interval) | | DC cost | dcCostTopEntries | dcCosts | CostOption | category / groupBy | ["default"] | | DC asset (count) | dcAssetTotalCounts (point-in-time) · dcAssetTopEntries (live snapshot) | dcAssets | AssetOption | category / groupBy | — | | DC utilization | — | dcUtilizations | DCUtilizationOption | — | — (fromDate+toDate+interval) | | Coverage | — | coverages | CoverageOption | — | — (month-N range) | | RI | — | riUtilizations · riUtilizationCoveragePage (per-reservation drill-down) | RIOption | — | — (month-N range) | | SP | — | spUtilizations | SPOption | — | — (month-N range) | | Tags | tagTopEntries | tagCoverage | TagOption | tagKeys | — | | Cost allocation | — | costAllocations | CostAllocationOption | — | — (option.startDate/endDate; NO filter arg) | | Cloud anomaly | anomalyTotalSummary | anomalyItems | AnomalyOption | — | thresholds = helloMCP.settings["cost-anomalies"] | | Recommendations | recommendationSummary | recommendationItems | RecommendationOption | — | ["amortized","discounted","term3Y"] + thresholds | NEVER SWAP THE DIMENSION FIELD: `*TopEntries`/summary use `category` + `limit`; series (`costs`/`aiCosts`/`saasCosts`/`k8sCosts`/`agentCosts`/`dcCosts`) use `groupBy` + `xAxis:"date"`. The wrong field passes `validate` but fails at `execute` with `Unrecognized name: undefined`. Agent cost dims: `agent_id`, `model_name`, `operation`, `user_id`, `tool_name`. Agent anomaly dims use the same spelling (`agent_id`, `agent_name`, `application_id`, `user_id`, `anomaly_type`, `severity`, `model_provider`, `model_name`). Items/summary list-field names are per-family, NOT `items`: `sessions`, `anomalies`, `assets`, `utilizations`, `agentCosts`, `dcCosts`, `k8sEfficiencyItems`, `aiAssistCostItems`, `aiAssistUtilizationItems`. ### DERIVED METRICS (no raw field exists — COMPUTE these; guessing gets them wrong) - K8s "Utilization Score" = avg(cpu_utilization, mem_utilization, disk_utilization, gpu_utilization), treating a null gpu as 0. - Coverage "Coverage %" = ri_cost / (ri_cost + on_demand_cost) — COST-based, NOT hours-based (hours give the wrong number). - RI "Utilization" = (reserved_hours − unused_hours) / reserved_hours. - SP "Utilization" = used_commitment / total_commitment; SP "Waste" = total_commitment − used_commitment; SP "Effective Cost" = total_commitment. - Efficiency/utilization % (k8s AND dc) are ALREADY in percent units — render as-is with `%`, never ×100. ### Choosing the Query — domain routing (cost is not the only area) Route via the QUICK ROUTING TABLE above; the bullets below add ONLY each family's traps (skip a family with no bullet — the table is enough). Universal: label = `groupName ?? groupId`; `*TopEntries` need `limit`; series need `groupBy`+`xAxis:"date"`; SaaS/GenAI/code-assist/agent are first-class — never fold into cloud `costs`. - GenAI cost: specific-model dim is 'model_name' (NOT bare 'model'); valid dims = `aiCostFilterOptions` field names; `aiCostLocations` is a map only — never sum it for a total (use `aiCostTopEntries.total`). - GenAI Insight: USAGE not spend; `aiInsightMetrics` = input/output_utilization_pct and REQUIRES fromDate+toDate+interval (month-only errors); returns [] when no insight data — report that honestly. - Code-assist: decide SPEND vs SEATS first — "cost per user" → `aiAssistCostItems`; "over quota / unused seats / adoption by department" → `aiAssistUtilizationItems` (quota_used vs quota_limit, overage_usage; quota_limit is null on unlimited tiers, don't divide by it). Spend queries carry "Cost" in the name, usage ones don't. - SaaS: pass provider:"all"; default groupBy 'provider_code'. - Agent cost: dims are 'agent_id','model_name','operation','user_id','tool_name'; `agentCostFilterOptions` has NO agent field — rank category 'agent_id' to list agents; line items carry no session/token → use Agent Session for those. - Agent session: `agentSessionTotalSummary` → total_count=sessions, total_agents, total_users, estimated_cost; page defaults to a rolling last-30-days. - Agent anomaly: total_count=anomalies, total_cost=cost impact, total_agent, total_user; pass `helloMCP.settings["agent-anomalies"]` (grouped shape, strip `alerts`) as `thresholds` to match the dashboard — omit only when the user wants ALL; rolling last-30-days. - DC cost: variant `default`|`chargeable` only (never the cloud discount/refund/tax/amortized flags); dims = `dcCostFilterOptions` field names. - DC asset (COUNT, not cost): for "how many resources", "total resources", or any resource COUNT — including "right now"/"current" — use `dcAssetTotalCounts` and read the LATEST COMPLETE month (last month): it is the POINT-IN-TIME monthly count (assets alive during month M) = the "Total Resources" KPI/trend. Use `dcAssetTopEntries` ONLY to RANK contributors ("top clusters/hosts/resources"); its `total` is the CURRENT-live snapshot grand total (`termination_time IS NULL`) and will NOT match the monthly count — never report `dcAssetTopEntries.total` as "how many resources". The two diverge once assets are terminated — by design, not an error. Rank category 'resource_type'|'cluster_id'|'host_id'. - DC utilization: `total_utilization`=score, `disk_utilization`=storage; values already in % (render as-is, never ×100); NOT `k8sUtilizations`. - Coverage / RI / SP: default WHOLE-MONTH ranges (fromDate = first of start month, toDate = first of the month AFTER, interval = `month-N`); never `day-N-custom` by default; keep the three SEPARATE. - RI drill-down (`riUtilizationCoveragePage`): run `riItems` first for the `id`, which is PROVIDER-DEPENDENT — azure → `resource_id`, others → `cloud_resource_id`. Same month as that row; set `pageSize` or `pageNo` is ignored; list field is `coverages`. - K8s efficiency vs utilization (decide FIRST): "efficiency / efficient / score" → `k8sEfficiencies` ONLY; "utilization / CPU·mem·GPU % / underutilized" → `k8sUtilizations` ONLY — different numbers for the same month, and the shared `K8sUtilizationOption` type name does NOT mean use `k8sUtilizations`. Efficiency fields are `_efficiency_pct`, already in % (0.26 = 0.26%, null gpu → 0%); list field `k8sEfficiencyItems`. - K8s cost: `yAxis` cost|idle_cost|usage_cost; for "high cost + low utilization" run `k8sCosts` AND `k8sUtilizations` and join on cluster/namespace. - Tags: pass `tagKeys` to focus a key; tag POLICIES come from `helloMCP.tagPolicies` (no query — pass a policy's `filter` as `TagOption.tagPolicy`; fallback to unscoped `tagCoverage`/`tagTopEntries` if none). `tagItems` (resource-level rows) is a RANGE query — pass `fromDate`+`toDate` (for one month, its first..last day); `month` alone is NOT applied to `tagItems` and silently returns current-month data. - Cost allocation: `costAllocations` only, NO `filter` arg; scope with option.startDate/endDate; headline = `total_cost`; omit id/parentId to list all, set option.id to drill in, option.parentId for children; report "Unallocated Cost" rows as-is. ### Choosing the Query — domain routing (cost is not the only area) Match the user's SUBJECT to the right tool family; each has its own typed Option input (introspect it before building). The "ranking vs. period" rule above (whole month → `*TopEntries`; custom/relative range → the series query) applies to resources, SaaS, and K8s cost exactly as it does to cloud cost. - Individual cloud RESOURCES / assets ("which resources drive cost", "list resources", resource-level drilldown) → `resources`, `resourceTopEntries`, `resourceItems`, `resourceFilterOptions` (`ResourceOption`). - SaaS spend ("SaaS", named SaaS products) → `saasCosts`, `saasCostTopEntries`, `saasCostItems`, `saasCostFilterOptions` (`CostOption`). First-class — never fold SaaS into cloud cost. - Commitment COVERAGE ("coverage", "covered vs on-demand") → `coverages`, `coverageItems`, `coverageFilterOptions` (`CoverageOption`). - Reserved Instances ("RI", "reservations", "RI utilization/waste") → `riUtilizations`, `riItems`, `riFilterOptions` (`RIOption`). Per-reservation drill-down ("what is reservation X covering", "which instances used this RI") → `riUtilizationCoveragePage` (paginated; see the RI drill-down trap below). - Savings Plans ("SP", "savings plan utilization/savings") → `spUtilizations`, `spItems`, `spFilterOptions` (`SPOption`). Keep Coverage / RI / SP SEPARATE — never merge them. - Kubernetes UTILIZATION ("k8s utilization", "CPU/GPU/memory efficiency", "underutilized namespaces", "GPU efficiency") → `k8sUtilizations`, `k8sUtilizationItems`, `k8sUtilizationFilterOptions` (`K8sUtilizationOption`). This is efficiency, NOT cost. - Kubernetes COST ("k8s cost", "namespace cost", "idle vs usage cost") → `k8sCosts`, `k8sCostTopEntries`, `k8sCostItems`, `k8sCostFilterOptions` (`CostOption`; `yAxis` cost/idle_cost/usage_cost). For "high K8s cost with low utilization", run `k8sCosts` AND `k8sUtilizations` and join on cluster/namespace. - Tagging analysis ("tag coverage", "untagged %", "tagging permeation") → `tagCoverage`, `tagTopEntries`, `tagItems`, `tagFilterOptions` (`TagOption`). Pass `tagKeys` to focus on a key (e.g. ['CostCenter']). - Cost Allocation model ("allocation model", showback/chargeback by model) → `costAllocationCosts` (`CostAllocationOption`; `option.id` selects the model; NO `filter` arg). Returns {date, cost} only — there is NO `unallocated` field; derive unallocated by comparing the model total to total cloud cost for the same period. For K8s / VMware / datacenter subjects do NOT inject `provider_code` (see Filter Inference Rules). ### Filter Inference Rules "cloud", "cloud providers", "cloud costs" and "cloud spend" — without Kubernetes, VMware or datacenter named — correspond to: filter: { provider_code: ["aws", "azure", "gcp", "oci"] } When the user refers to "Kubernetes", "k8s", "VMware", or "datacenter" — do NOT inject `provider_code`. Use the dedicated Kubernetes/VMware/datacenter queries or filters instead. ### Discovering Filter Values ("what options do I have for X?") When the user asks what values are available for a dimension — e.g. "what tenants / tenant names do I have?", "what billing accounts / locations / products can I filter by?" — call `costFilterOptions` and read the matching field (e.g. `tenant_name`, `billing_account_name`) from the result. This is also the prerequisite step before applying any filter: resolve the user's plain-language name to a valid ID/value first. `*FilterOptions` queries (costFilterOptions, etc.) REQUIRE `fromDate` and `toDate` in the `option` — they only return values that appear in cost data within that window, so omitting the range can yield an empty list. When the user gives no period, default to the last 3 months from `helloMCP.datetime` (fast — a wide scan here is the main source of slow filter-option calls); widen only if an expected value is missing, and never request more than a 12-month window. For CLOUD filter options (`costFilterOptions`) include the standard `options: ["default","discount","refund","tax"]`; for `resourceFilterOptions` pass `options: ["default"]` (resources do NOT take the adjustment flags); for SaaS/GenAI filter options (`saasCostFilterOptions`, `aiCostFilterOptions`) pass `options: []`, and for K8s filter options (`k8sCostFilterOptions`) pass `options: ["default"]` — none of them use the adjustment flags (see Cost Variant Selection). ### Cost Variant Selection (STANDARD CLOUD COST ONLY) The adjustment-flag + variant logic below applies ONLY to standard cloud cost (`costs`, `costTopEntries`, `costVariances`, `costLocations`, `costFilterOptions`). `options` carries the 3 adjustment flags `"discount"`, `"refund"`, `"tax"` PLUS exactly ONE variant. Never combine `default`/`net`/`amortized`/`net_amortized`. - **Default:** use the fixed baseline `["default","discount","refund","tax"]` (the 3 adjustment flags plus the `default` variant = actual/blended). The baseline variant is `default`, not `amortized`. - If the user says "amortized" → swap the variant flag to `amortized`, e.g. `["amortized","discount","refund","tax"]`. - If the user says "net" / "after credits" / "after discounts" → use `net_amortized`. - If the user says "gross" / "list price" / "on-demand" → use `amortized`. NOTE: `costVariances` accepts all four variants (`default`/`net`/`amortized`/`net_amortized`), same as `costs` (verified live — `net_amortized` changes the numbers, it is not silently dropped). **Resources and tags do NOT take the adjustment flags.** `ResourceOption`/`TagOption` `options` defaults to `["default"]` (variant may be `default` or `amortized` only — never `net`/`net_amortized`, never discount/refund/tax). **Savings / recommendations (`RecommendationOption`) use their own `options`, NOT the cloud flags.** Default `["amortized","discounted","term3Y"]` (the tenant savings default — cost/savings return null/0 unless `options` is set). Compose exactly THREE, one from each group: cost field `"default"`|`"amortized"`; savings field `"actual"`|`"discounted"`|`"optimal"`; commitment term `"term1Y"`|`"term3Y"` (3Y gives larger savings). `"optimal"` → monthly_optimal_savings/cost; `"discounted"` → monthly_amortized_savings/cost. Pair `options` with `thresholds` = `helloMCP.settings["savings-thresholds"]` (the savings floor). For a PAST month's recommendations, pass `month` (first of that month) — recs are stored per `invoice_month`. `todayDate` is a forecasting baseline, NOT a historical filter: it is not applied to recommendations and returns current-month recs. **SaaS, GenAI, and Kubernetes cost queries do NOT use cost-variant or adjustment flags.** `saasCosts`/`saasCostTopEntries`/…, `aiCosts`/`aiCostTopEntries`/…, and `k8sCosts`/`k8sCostTopEntries`/… share the `CostOption` input but ignore amortized/net/ net_amortized and discount/refund/tax — those are cloud-only. Applying them there yields a figure that does NOT reconcile with cloud cost (data discrepancy). `options` is a required field: pass `options: []` for SaaS and GenAI, and `options: ["default"]` for Kubernetes cost (variant `default` | `chargeable` — `chargeable` is on-prem/K8s-on-prem only; same for datacenter cost). K8s cost's cost metric is selected with `yAxis` (cost / idle_cost / usage_cost), NOT with the cloud adjustment flags. `k8sUtilizations` takes an OPTIONAL cost-variant `options` (`default` | `chargeable`) — omit it for pure utilization %, pass it only to relate utilization to cost. ### Default Limits - If the user does not specify a limit or top-N, default to `limit: 20`. - If the user says "top N", "first N", or "show me N" → use that N exactly. - If the user says "all" or "everything" → use `limit: 100` (hard ceiling) and tell them results are capped. - Always pair `limit` with a deterministic `orderBy` (typically cost descending) so truncation is meaningful. ### Building the Operation: Typed Inputs `option`/`filter`/`search` are TYPED inputs (introspection, `validate`, `execute` agree). Declare them with their real types — standard GraphQL variables: - `option`: `CostOption!` (cloud cost, SaaS cost, K8s cost, GenAI cost) / `RecommendationOption!` / `AnomalyOption!` / `ResourceOption!` (resources) / `CoverageOption!` · `RIOption!` · `SPOption!` (commitments) / `K8sUtilizationOption!` (k8s utilization AND k8s efficiency — `k8sEfficiencies`/`k8sEfficiencyItems`/`k8sEfficiencyFilterOptions`, NOT `CostOption`) / `TagOption!` (tagging) / `CostAllocationOption!` (cost-allocation models + series, `costAllocations`); `filter`: `Filter` (omit for `costAllocations`); `search`: `Search`. Never `$option: Json!`. - Only `thresholds` (Recommendation/Anomaly) and `tags`/`vtags` (Filter) are the `Json` scalar — pass those as `$thresholds: Json` variables (a Json value with quoted keys is not valid inline syntax). ### What execute depends on The most common failure is a query referencing a type that was never introspected: names guessed by analogy with another family read as plausible, then fail at validate or execute. What determines whether a query will run: the target query, every custom Input Object and Return Object it references, and whether any of those are still unintrospected — `introspect` is what supplies them. Defaults exist for the gaps that recur, so most questions carry enough information already: the cloud provider filter (see Filter Inference Rules), `limit` (20), and the cost variant (`["default","discount","refund","tax"]`). A time range and a grouping dimension have no safe default when the question implies neither. ### Pre-Execution: Field Checklist Before sending the query, verify against your cached introspection data: 1. Every field marked "EFFECTIVELY REQUIRED" or with a `!` suffix must be present — omitting one fails. 2. Every field you're selecting actually exists on the return type. 3. All enum/groupBy values (e.g. groupBy, yAxis) are derived from introspection — never guessed. 4. `options` is set per the Cost Variant Selection rule above (cloud → one cost type + the 3 flags; resource/tag/K8s/datacenter → `["default"]`; SaaS/GenAI/agent/code-assist → `[]`; savings → `["amortized","discounted","term3Y"]`). 5. All dates are formatted as "YYYY-MM-DD". Month-level queries always use the first day: "2026-02-01", never "2026-02-28". 6. `limit` is set per the Default Limits rule above, paired with a deterministic `orderBy`. If validation fails, do NOT guess the fix. Re-read your introspection cache or re-run `introspect` on the failing type. On any execution error: read the full error message, identify the exact failing field or argument, re-introspect that specific type, then retry once. If it fails again, report the error verbatim — do not guess further. ### Interpreting results The API follows FOCUS (FinOps Open Cost & Usage Specification) terminology, so figures are comparable across AWS/Azure/GCP/OCI. **FOCUS cost-metric naming** — what each variant is called; a single figure never combines two of them: - actual / blended (no net/amortized flag) → call it "Billed Cost" - amortized → "Amortized Cost" (FOCUS Effective Cost) - net_amortized → "Net Effective Cost" (after credits/discounts) These variants exist for standard cloud cost and resources ONLY. SaaS, GenAI and Kubernetes cost have no variant, so no Billed/Amortized/Net label applies to them — they are plain "SaaS cost" / "GenAI cost" / "Kubernetes cost" (K8s additionally has a yAxis basis: total / idle / usage cost). **Dimension field reference** — the FOCUS-style business term each raw API field denotes: - provider_code → Provider · product_name → Service · usage_account_id → Account - billing_account_id → Billing Account · location_id → Region · cost_type → Charge Category - tenant_id / tenant_name → Tenant (Customer) · sku_id → SKU · namespace → Namespace - cluster_id → Cluster · instance_type → Instance Type · resource_group_id → Resource Group - monthly_optimal_cost → Optimal Monthly Cost · monthly_savings → Potential Monthly Savings - model_name → Model · model_provider_code → Model Provider · model_type → Model Type - operation → Operation · api_key_id → API Key · gateway_id → Gateway · user_id → User · platform → Platform **Cost values:** - Negative values are credits and refunds. - Costs are denominated in `helloMCP.currency`, an ISO 4217 code that is not always USD; the field can be missing or empty. - Symbols for the codes that occur in this tenant base: `USD` $ · `EUR` € · `GBP` £ · `JPY` ¥ · `CNY` ¥ · `INR` ₹ · `AUD` A$ · `CAD` C$ · `CHF` CHF · `KRW` ₩ · `BRL` R$ · `RUB` ₽ · `THB` ฿. Codes outside this list have no symbol recorded here, and the code itself is the unambiguous form (`ZAR 123.45`). - Totals & % share: prefer the API's aggregated `total` (e.g. `CostTopEntriesResponse.total`, `aiCostTopEntries.total`) — it is the authoritative grand total across all groups, and % share is computed against it. Take it ONLY from the `total` field, never by summing the top-N rows (that omits the tail). Note it excludes the blank/empty-`groupBy` bucket, a small known undercount — accepted, do not "correct" it by summing the series. Only when the query has no aggregate total (a series query like `costs`, used for a custom/relative range) and the user needs a period total may you sum the returned points — label it "computed from returned data" and note it reflects only the returned series. - Never add both gross and net cost fields together. Pick one cost variant per query. **Errors, empty and truncated results:** - A backend failure (a daily/custom-range view unavailable, a table "not found") is specific to that query shape — a different, unrelated shape does not address it. - Common causes of an empty result set: the date range, `options` unset, an invalid `groupBy` value, or filters that over-constrain. - A result count equal to the requested limit (the default is 20) means the set is probably truncated and more rows exist. - A period or granularity other than the one asked for is a different figure, and no authoritative grand total exists unless the query returned one. ### Reporting limits of the data A failed query, a partial or truncated result, a null value, and a period or granularity that differs from the one requested are all facts about the result and belong in the answer alongside it.

execute

Discover Mavvrik REST management read operations (28 across 13 areas) by keyword. Areas: account, agentic, ai-account, budget, cost-allocation, perspective, saas, settings, team, tenant, usage-account, user, user-settings. Search by an area name or keyword; returns operation names and their parameters. Then call rest_invoke with an operation name and its arguments.

rest_search

**mvk-hello** Session initialization — call ONCE at the start of every session. Returns a Json object: { "name": "...", "datetime": "...", # reference timestamp for all date-sensitive queries "currency": "USD", # tenant display currency "uiOptions": { # the effective cost options / anomaly thresholds this tenant/user "cost": { "options": ["discount","refund","tax"] }, # gets when those inputs are OMITTED "anomaly": { "thresholds": [{ "id":"default","name":"Default","scope":null, "thresholds":[{"type":"amount","value":0.01,"relationship":"AND"}] }] } } } REUSE `uiOptions.anomaly.thresholds` VERBATIM as AnomalyOption.thresholds whenever the user wants "the configured / my usual threshold" — it is already in the canonical GROUPED shape [{ id, name, scope, thresholds:[{type,value,relationship}] }]. To override, keep that exact grouped shape and change only the inner rule values (e.g. value: 50) — never flatten it to [{type,value}]. A hello group may also carry an `alerts` array — strip it; only {id,name,scope,thresholds} is read. `uiOptions` is the no-override default and may age within a session. The server applies NO anomaly-threshold default — it filters by EXACTLY the `thresholds` you pass, so pass `uiOptions.anomaly.thresholds` (omitting it returns ALL anomalies).

helloMCP

Validates a GraphQL operation against the schema. Use the `introspect` tool first to get information about the GraphQL schema. Operations should be validated prior to calling the `execute` tool. Hint: ## Validation `validate` checks an operation against the schema without running it, so a schema error surfaces here rather than as an execute failure. - If validation passes → proceed to execute. - If validation fails → re-introspect the failing type. Do NOT guess the fix. - If validation fails twice on the same type → re-introspect from the root query signature down to the failing type, then try again.

validate