Skip to main content
Glama

Costory: Your Finops MCP

by io.costory.app-api
OverviewDiscussionsAdmin

get

Read-only

Fetch a V2 dashboard, budget, cost alert, report, virtual dimension, or BigQuery job by ID. Response includes a type discriminator (dashboard | budget | costAlert | report | virtualDimension | bigquery_job) — branch on it.

BigQuery jobs: pass id <project>:<location>.<job_id> (auto-detected from that shape, or set type: "bigquery_job"). Location is case-insensitive (EU and eu are the same). Loaded with the free Jobs API (jobs.get) — user_email, referenced tables, slot/bytes metrics, query_text, and performance_insights — plus stages and children when it is a script parent. Each stage has its name, slotMs, shuffle bytes, and the SQL clause (FROM / JOIN / WHERE / GROUP BY) that places it in query_text. Stages are sorted by slotMs descending. Timing histograms and column lists are omitted. The first fetch is cached in Postgres (a finished job never changes); the second call is a cache hit. Use it to investigate a BigQuery cost line's underlying query.

Dashboard / budget / cost alert / report / virtual dimension lookups:

Budgets: pass the parent budget id (from search) or a budget version id; response includes budgetVersionId for query, plus costMetricId, currency, virtualDimension (id, name, bqName, values), excludedValues, lines, includedVirtualDimensionValues, filterCelRestrictToIncludedLines, and filterCelExcludeExcludedVirtualDimensionValues for aligning query cost with budget. howToQueryAlignedCost gives concrete example payloads.

Cost alerts: pass the alert id (from search or list_alerts); response includes alert configuration plus firingHistory (every stored firing day and group values that fired). The payload includes scopeId, the saved team scope. The returned queries are the stored internal shape — read-only, and they do not contain that scope filter. To change the series with update_alert, write a fresh queries array with filterCel exactly as for create_alert; do not echo these back.

Reports: config in words plus run-health (status, nextRunDate, lastRunHealth, widgets array, recent per-destination delivery with executionIds). Read-only. To inspect a specific delivery's content, call get_report_execution (then get_report_execution_widget for drill-down).

Virtual dimensions: id / virtualDimensionId (same), hasPendingDraft, immutable bqName (BigQuery/CEL field for groupBy/filterCel — never derive from display name); published and optional draft (name, description, tags, computeStatus, values, rules, leftoverRule; draft may include draftValidation); dependencies. values is derived — output only. leftoverRule is separate from rules — do not put it in the rules array or pass it to update. For updates, copy rules from draft if pending else published, project each rule to { id, name, conditionCel, allocation } (omit position, isLeftovers, and any leftover/catch-all rule), and pass that full rules array to update_virtual_dimension_draft. Call get_skill with skillId: "virtual-dimensions" for allocation shapes and workflow.

Dashboards: call get_skill with skillId: "dashboards" before create/update. Chart widgets include x/y/w/h and resolved queryConfig; text widgets have type: "text" and textContent. After fetch, use get_dashboard_widget_data / get_dashboard_widget_image, or update_dashboard to mutate.

Use "search" (or list tools) first to discover IDs. EXAMPLE: "Open the Kubernetes dashboard" (after search returned its ID) → { id: "clx9abc123" }

Input Schema

NameRequiredDescriptionDefault
idYesID of a V2 dashboard, budget, cost alert, report, virtual dimension, or BigQuery job (from search / list tools). For budgets, pass parent budget id or budget version id. For BigQuery jobs, pass `<project>:<location>.<job_id>` — location is case-insensitive. Response includes a `type` discriminator: dashboard | budget | costAlert | report | virtualDimension | bigquery_job.
slugNoOrganization slug. Omit to auto-detect from your account (fails if you belong to multiple orgs).
typeNoRestrict the lookup to one resource type. Omit to try every type; a BigQuery job id is also auto-detected from its `<project>:<location>.<job_id>` shape.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / id / description
      Previous value: -"ID of a V2 dashboard, budget, cost alert, report, virtual dimension, or BigQuery job (from search / list tools). For budgets, pass parent budget id or budget version id. For BigQuery jobs, pass the canonical `<project>:<location>.<job_id>` id. Response includes a `type` discriminator: dashboard | budget | costAlert | report | virtualDimension | bigquery_job."New value: +"ID of a V2 dashboard, budget, cost alert, report, virtual dimension, or BigQuery job (from search / list tools). For budgets, pass parent budget id or budget version id. For BigQuery jobs, pass `<project>:<location>.<job_id>` — location is case-insensitive. Response includes a `type` discriminator: dashboard | budget | costAlert | report | virtualDimension | bigquery_job."
  2. Changed2 schema fields changed
    • changedInput schema / properties / id / description
      Previous value: -"ID of a V2 dashboard, budget, cost alert, report, or virtual dimension (from search / list tools). For budgets, pass parent budget id or budget version id. Response includes a `type` discriminator: dashboard | budget | costAlert | report | virtualDimension."New value: +"ID of a V2 dashboard, budget, cost alert, report, virtual dimension, or BigQuery job (from search / list tools). For budgets, pass parent budget id or budget version id. For BigQuery jobs, pass the canonical `<project>:<location>.<job_id>` id. Response includes a `type` discriminator: dashboard | budget | costAlert | report | virtualDimension | bigquery_job."
    • addedInput schema / properties / type
      Added value: +{
+  "description": "Restrict the lookup to one resource type. Omit to try every type; a BigQuery job id is also auto-detected from its `<project>:<location>.<job_id>` shape.",
+  "enum": [
+    "dashboard",
+    "budget",
+    "costAlert",
+    "report",
+    "virtualDimension",
+    "bigquery_job"
+  ],
+  "type": "string"
+}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds substantial behavior beyond that: Postgres caching with a guaranteed second-call cache hit for BigQuery jobs, what is deliberately omitted (timing histograms, column lists), that returned `queries` are a read-only internal shape lacking the scope filter and must not be echoed back, and that `values` on virtual dimensions is derived/output-only. This is unusually rich disclosure for a read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the discriminator and ID-discovery guidance, then cleanly partitioned by resource type, so an agent can jump to the relevant paragraph. It is nevertheless very long and enumerates return payload fields (costMetricId, filterCelRestrictToIncludedLines, etc.) that read as spec-dump; with no output schema most of that detail earns its place, but the volume is close to the limit of what a selector can absorb.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries the full burden of return-value semantics, and it does: per-type payload contents, the `type` discriminator, BigQuery stage/children behavior, and the alert `queries` shape. For a six-way polymorphic getter sitting among dozens of get_/search/list siblings, nothing an agent needs to invoke or interpret this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3 and much here (BigQuery id shape, budget parent/version id, the type enum) is already in the schema. The description still adds operating meaning: BigQuery ids are auto-detected from their shape and location is case-insensitive, omitting `type` tries every type, and slug auto-detection fails for multi-org accounts. That is above the baseline, though not a full compensation case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb + resource list ('Fetch a V2 dashboard, budget, cost alert, report, virtual dimension, or BigQuery job by ID') and immediately explains the `type` discriminator used to branch. Despite the generic name 'get', an agent can distinguish this polymorphic fetcher from get_report_execution, get_dashboard_widget_data, and the search/list siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'Use "search" (or list tools) first to discover IDs', plus named hand-offs to get_report_execution for delivery content, get_dashboard_widget_data/get_dashboard_widget_image after a dashboard fetch, get_skill with skillId 'dashboards'/'virtual-dimensions' before mutations, and update_alert for alert rewrites. Both the when-to-use and the when-to-use-something-else conditions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Costory: Your Finops MCP toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources