Feature Overview

The CoreStack MCP Server is a Platform-level integration that exposes CoreStack’s FinOps, Graphion, Assessment, and Workload capabilities as a set of callable tools, following the Model Context Protocol (MCP). It is most relevant when you are connecting an AI agent, automation script, or MCP-compatible client to CoreStack and need programmatic access to cost data, security posture, compliance assessments, or workload inventory across AWS, Azure, GCP, and OCI accounts, instead of using the CoreStack web console.

This capability is most valuable to platform integrators, automation engineers, and AI-agent developers who need to read or act on CoreStack data outside the browser. It is not a replacement for the CoreStack web console — UI-only configuration tasks (for example, custom dashboard layout or SSO setup) still require the console, and every tool call still runs inside your existing CoreStack permissions rather than granting new access.

How It Works

When an MCP client calls authenticate, CoreStack establishes a session scoped to the caller’s last-used master account and tenant, and every subsequent tool call reuses that session’s implicit auth context automatically. From there, the client selects the tools it needs: read-only tools such as get_cloud_accounts or list_assessment_runs return data immediately, while the four tools marked Destructive create or modify CoreStack data and should be called only after the inputs are confirmed. Once a tool call completes, its response comes back in a consistent {Summary, Output}-style envelope (the exact keys vary by tool) that the client parses and acts on programmatically. Because tool numbering and domain grouping mirror the underlying tool registry, the same session moves between FinOps, Graphion, Assessment, and Workload tools without re-authenticating — session state, not tool domain, is what changes between calls.

Prerequisites

Before you begin, ensure the following:

• Role: Your CoreStack user or service account has a role assigned that grants access to the module(s) you intend to call.
• Permissions: For any tool marked Destructive (send_agent_query, file_bug, submit_assessment_answer, create_workload), your role must also include Create/Update access for the relevant module, since these calls modify CoreStack data.
• Prior setup: Your CoreStack tenant already has the cloud accounts, portfolios, or assessment definitions you plan to query onboarded — the MCP tools read and act on existing CoreStack data; they don’t onboard new accounts.
• Access: You have valid CoreStack API credentials (access key, secret key, and API URL) and an MCP-compatible client capable of connecting to the CoreStack MCP server endpoint.

Connecting to and Calling CoreStack MCP Tools

Configure your MCP client with your CoreStack API credentials before making any tool calls; the client passes these as an implicit session context on every request. Follow the steps below to establish a session and make your first tool calls.

Step 1: Authenticate the session

Call authenticate with no parameters. CoreStack establishes a session and auto-selects your last-used master account and tenant, returning master_account_id, tenant_id, and the list of available_master_account_ids you can switch between.

Step 2: Select a tenant or master account, if needed

If the auto-selected tenant or master account from Step 1 isn’t the one you need, call set_active_tenant or set_master_account with the tenant_id or master_account_id you want. Skip this step if the defaults from authenticate are already correct.

Step 3: Identify the tool you need

Check the Domain Summary in Appendix A to find the tool that covers your task — FinOps for cost and billing questions, Graphion for application security posture, Assessment for Well-Architected reviews, or Workload for resource inventory.

Step 4: Call the tool with its required parameters

Call the selected tool, supplying every parameter marked Required in its Reference entry. For example, call get_cloud_accounts with tenant_ids to list the cloud accounts available for cost queries.

Step 5: Confirm inputs before calling a Destructive tool

Before calling a tool marked Destructive, double-check the inputs are correct — these calls create or modify CoreStack data and can’t be undone simply by calling the tool again with different parameters.

Additional Tasks

Analyzing Cloud Costs (FinOps)

Build a filter with build_filter_query, then pass it to get_cost_aggregation_trend or get_anomalies to investigate spend over time or unexpected cost spikes. Pair this with get_savings_summary to see potential and realized savings in the same session

Reviewing Application Security Posture (Graphion)

Call portfolio_list_and_retrieval to find the portfolio you’re investigating, then dashboard_top_actionable_issues to get a risk-prioritized list of vulnerabilities and misconfigurations. Use vulnerability_get_details_batch to pull full CVE detail for any issues you need to triage further.

Running a Well-Architected Framework Assessment

Call list_assessment_definitions to find the assessment you want, list_assessment_runs to see its run history, and get_pillar_scores to see the resulting pillar-by-pillar scores. Use submit_assessment_answer (Destructive) to record answers against best practices as you work through the assessment.

Querying Workload Resources

Call list_workload_definitions to see the workloads configured for your tenant, then query_workload_resources to pull the resource inventory for a specific workload tier. Use get_resource_batch to retrieve full configuration detail for any resource IDs returned.

Complete MCP Tool Reference

This document provides standardized MCP-format documentation for the tools exposed by the CoreStack unified MCP server. It catalogs every tool across the platform — FinOps, Graphion, Assessment (Well-Architected Framework), Workload, and Common/Auth domains.

The reference covers 100 tools across 5 domains: Common/Auth (10), FinOps (24), Graphion (45), Assessment (15), and Workload (6). Tool numbering matches the order of the underlying tool registry for cross-reference.

Every tool takes an MCP session/auth context as an implicit first argument supplied automatically by the MCP client/server transport; it is omitted from the parameter tables below. In each table, a parameter is "Required" when it has no default value. Unless otherwise noted, all tools validate the caller’s CoreStack session before calling the backend API and are read-only; tools that create or modify data are marked Destructive.

FinOps

FinOps — Billing & Cost Aggregation

1. get_cost_aggregation

Retrieve snapshot cost aggregation totals grouped by dimensions for a time period (POST /v2/billing/aggregation) — a single aggregated snapshot, not a time series.

Parameters

Returns: dict[str, Any] — {Summary: {total_records}, Output: <aggregated cost data>}.

2. get_billing_metrics

Return the billing metrics (cost types) available for the given cloud accounts, with frontend-friendly display names (including virtual Margin metrics).

Parameters

Returns: dict[str, Any] — {Summary: {total_records}, Output: [{backend_key, display_name, provider_labels?, dependent_sources?, is_margin?}, ...]}.

3. get_cost_aggregation_trend

Low-level passthrough tool for parameterized billing queries against the cost aggregation layer — an escape hatch for any cost/usage question not covered by higher-level tools. Returns a time series (not a single snapshot).

Parameters

Returns: dict[str, Any] — {Summary: {total_records}, output: [<trend points>]}.

4. get_billing_usage_trend

Retrieves billing usage trends over time — resource consumption (GB, hours, API calls), not cost.

Parameters

Returns: dict[str, Any] — {summary: {total_records}, output: [<usage trend points with identity/timestamps/values>]}.

5. get_billing_rate_trend

Retrieves billing rate trends over time — per-unit cost ($/GB, $/hour), computed as cost ÷ usage. Zero usage yields None rates.

Parameters

Returns: dict[str, Any] — {summary: {total_records, undefined_rate_count}, output: [<rate trend points>]}.

6. build_filter_query

Build a QueryOperator filter tree from up to 34 structured filter dimensions, composed via AND/OR/NOT. Must always be called first in FinOps billing workflows; rejects an empty .

Parameters

Returns: dict — a QueryOperator dict with a __type field. Raises ValueError for malformed sub-filters/tags/field_presence/dimensions, or empty input with no other filter set.

FinOps — Accounts

7. get_cloud_accounts

Discover cloud accounts (service accounts) for one or more tenants — the primary account-discovery tool. Call before any cost/billing tool that needs service_account_ids.

Parameters

Returns: dict[str, Any] — {aws_ids, azure_ids, gcp_ids, oci_ids, other_ids, total, tenants? (if include_hierarchy)}.

FinOps — Budgets

8. get_budgets

Lists all budgets with aggregated summary and health indicators. Filters by status, provider, scope, frequency; calculates health percentages and over-budget items.

Parameters

Returns: dict[str, Any] — {summary: {total_budgets, total_budget_amount, total_actual_spend, exceeded_count, forecast_exceeded_count, health_pct, by_scope, by_frequency, by_status, top_exceeded, total_records}, output: {budgets: [...]}}. Returns an empty list/summary (not an error) when no budgets match.

9. get_budget_detail

Retrieves detailed configuration and metrics for a single budget by ID (merges view, alerts, and history into one response). Auxiliary calls (alerts/history) fail open.

Parameters

Returns: dict[str, Any] — {summary: {total_records}, output: {budget_name, budget_id, frequency, status, currency, scope, amount, thresholds, alerts, period, history|None}}.

FinOps — Reserved Instances & Savings

10. get_ri_recommendations

Get Reserved Instance (RI) purchase recommendations to reduce costs.

Parameters

Returns: dict[str, Any] — {Summary: {total_records}, Output: <RI recommendation data>}.

11. get_ri_reservation_coverage

Get reservation coverage for a specific RI — the percentage of eligible usage covered.

Parameters

Returns: dict[str, Any] — {cloud_account_id, reservation_id, date_filter, Output: <coverage data>}.

12. get_ri_reservation_utilization

Get utilization metrics for a specific RI — how much of the purchased capacity is actually used.

Parameters

Returns: dict[str, Any] — same shape as get_ri_reservation_coverage.

13. get_ri_reservations

List Reserved Instance reservations to discover reservation IDs and basic details.

Parameters

Returns: dict[str, Any] — {Summary: {total_records}, Output: [<reservations>]}.

14. get_cost_optimization_by_types

Fetch cost optimization data from the executive-dashboard cost-optimization-by-types endpoint.

Parameters

Returns: dict[str, Any] — {"data": [<recommendations with cost_savings, optimization_type, cloud_account, cloud_provider, region?, resource_name, resource_type, resource_id, resource_category, optimization_name>]}.

15. get_right_sizing_recommendations

Fetch detailed right-sizing recommendations for a specific cloud account — current vs. recommended SKU per resource.

Parameters

Returns: dict[str, Any] — {"data": {total_count, recommendation_data: [{resource_id, resource_name, current_sku, recommended_sku, optimization_type, potential_est_cost_saving, region, cloud_provider, resource_type}]}}.

16. get_recommendation_resources

Retrieve resource-level details for usage optimization recommendations — drill-down of a recommendation's underlying resources with current vs. recommended config.

Parameters

Returns: dict[str, Any] — {Summary: {total_records}, Output: {request_type, cloud_account_id, total_resources, total_pages, page_savings, resources_on_page, resources: [{resource_id, resource_name, resource_type, current_sku, recommended_sku, estimated_cost_saving, region, impact_level, optimization_type, status, summary_text}]}}.

17. get_savings_summary

Get a combined savings overview: RI recommendation savings + cost saved to date.

Parameters

Returns: dict[str, Any] — {summary: {total_records: 1}, output: {recommendations_count, potential_savings, total_reservations, cost_saved_till_date, cost_saved_current_month, potential_recommended, by_cloud, currency}}.

18. get_savings_plans_details

List purchased savings plans with details, excluding utilization time-series.

Parameters

Returns: dict[str, Any] — {Summary: {total_records}, output: {plans: [<plan metadata: plan_id, plan_name, plan_type, plan_scope, service_account_id, start_date, end_date, term, payment_option, commitment_amount, upfront_cost, currency, instance_family, provisioning_state, utilization_percentage>], total, page, page_size}}.

19. get_savings_plans_utilization

Fetch paginated utilization time-series for a single purchased savings plan.

Parameters

Returns: dict[str, Any] — {Summary: {total_records}, output: {plan_id, plan_name, plan_type, service_account_id, utilization_percentage, metrics: [{usage_date, avg/max/min_utilization_percentage}], total, page, page_size}}.

20. get_savings_plans_coverage

Compute portfolio-wide savings plans coverage summary: active vs. inactive counts, commitment totals, average utilization, breakdowns, and plans expiring soon.

Parameters

Returns: dict[str, Any] — {Summary: {total_records: 1}, output: {total_plans, active_plans, inactive_plans, total_commitment_per_hour, total_upfront_cost, average_utilization_percentage, by_plan_type, by_payment_option, by_term, by_service_account, expiring_in_30_days, expiring_in_90_days}}.

FinOps — Anomalies & Dimensions

21. get_anomalies

Detect and summarize billing cost anomalies (mirrors the UI Anomaly Summary/Details page). Scopes to active accounts and category-level, above-threshold anomalies with positive cost impact.

Parameters

Returns: dict[str, Any] — {Summary: {total_records: 1}, Output: {period, anomaly_status, total_anomalies, total_cost_increase, by_type, by_product, by_resource, by_account, top_anomalies, trend}}.

22. get_anomaly_resources

Drill down to resource-level anomaly details.

Parameters

Returns: dict[str, Any] — {Summary: {total_records: 1}, Output: {period, total_resources_with_anomalies, top_resources: [{resource_id, product, resource, account_id, date, type, impact, actual, expected, upper_bound, lower_bound}], by_product_category}}.

23. get_anomaly_dimension_grouping

Retrieve grouping-rule-wise cost anomalies for cost dimensions (the UI "Group" view).

Parameters

Returns: dict[str, Any] — {Summary: {total_records: 1}, Output: {period, currency, anomaly_status, total_anomalies, total_cost_increase, by_dimension, by_grouping_rule, by_product, by_resource, top_anomalies, trend}}.

24. get_dimensions

Retrieve cost dimensions used for grouping and filtering FinOps data.

Parameters

Returns: dict[str, Any] — {total_dimensions, dimensions_returned, by_type: {type: [{id, name, owner, active}]}, dimensions: [{id, name, type, owner, active, anomaly_detection, description, attributes, group_by_key_examples}]}.

Graphion

Graphion — Portfolio / Application / Project

1. portfolio_list_and_retrieval

List and retrieve portfolios for the selected tenant.

Parameters

Returns: dict[str, Any] — list of portfolio details under Output (or message/results if none found).

2. portfolio_get_details

Retrieve detailed information for a specific portfolio.

Parameters

Returns: dict[str, Any] — complete portfolio details under Output.

3. application_list_and_retrieval

List and retrieve applications for the selected tenant.

Parameters

Returns: dict[str, Any] — list of application details under Output.

4. application_get_details

Retrieve detailed information for a specific application.

Parameters

Returns: dict[str, Any] — complete application details under Output.

5. project_list_and_retrieval

List and retrieve projects for the selected tenant.

Parameters

Returns: dict[str, Any] — list of project details under Output.

6. project_get_details

Retrieve detailed information for a specific project.

Parameters

Returns: dict[str, Any] — complete project details under Output.

Graphion — SBOM

7. sbom_definition_get_batch

Batch retrieve detailed information for multiple SBOM definitions by their IDs.

Parameters

Returns: dict[str, Any] — list of SBOM definition details under Output.

8. sbom_definition_list_and_retrieval

List and retrieve SBOM definitions for the selected tenant.

Parameters

Returns: dict[str, Any] — list of SBOM definition details under Output.

9. sbom_get_details

Retrieve detailed information for a specific SBOM definition.

Parameters

Returns: dict[str, Any] — complete SBOM definition details under Output.

10. sbom_version_get_details

Retrieve detailed information for a specific SBOM version.

Parameters

Returns: dict[str, Any] — complete SBOM version details (components + vulnerabilities) under Output.

11. sbom_version_list_for_definition

List all versions for a specific SBOM definition.

Parameters

Returns: dict[str, Any] — list of all SBOM versions under Output.

Graphion — Container Findings

12. container_findings_list_and_retrieval

List and retrieve container security findings for the selected tenant.

Parameters

Returns: dict[str, Any] — list of container findings under Output (Dockle/Hadolint finding objects).

13. container_findings_get_batch

Get detailed information for multiple container findings by their IDs.

Parameters

Returns: dict[str, Any] — detailed container finding info under Output.

Graphion — Dashboards & Vulnerabilities

14. dashboard_portfolio_hierarchy

Get portfolio hierarchy summary showing organizational structure.

Parameters

Returns: dict[str, Any] — portfolio → application → SBOM hierarchy under Output.

15. dashboard_sbom_components_summary

Get SBOM components summary with details of all SBOMs and their associated components.

Parameters

Returns: dict[str, Any] — SBOM components summary under Output.

16. dashboard_sbom_vulnerabilities_summary

Get SBOM vulnerabilities summary with details of all SBOM vulnerabilities.

Parameters

Returns: dict[str, Any] — SBOM vulnerabilities summary under Output.

17. dashboard_top_actionable_issues

Get top 10 risk-prioritized actionable issues in the current context.

Parameters

Returns: dict[str, Any] — top 10 prioritized issues under Output.

18. dashboard_vulnerabilities_by_component

Get aggregated vulnerability counts grouped by component properties.

Parameters

Returns: dict[str, Any] — aggregated vulnerability counts under Output.

19. dashboard_vulnerability_trend_by_severity

Get vulnerability trend data grouped by severity over time.

Parameters

Returns: dict[str, Any] — vulnerability counts by severity over time under Output.

20. dashboard_sbom_build_difference_trend

Get trend of build differences showing new and resolved vulnerabilities/components.

Parameters

Returns: dict[str, Any] — build difference trends under Output.

21. sbom_version_compare_builds

Compare two SBOM builds to see differences in components and vulnerabilities.

Parameters

Returns: dict[str, Any] — component/vulnerability differences under Output.

22. sbom_components_get_batch

Batch retrieve detailed information for multiple SBOM components by their IDs.

Parameters

Returns: dict[str, Any] — list of component details under Output.

23. sbom_version_get_batch

Batch retrieve detailed information for multiple SBOM versions by their IDs.

Parameters

Returns: dict[str, Any] — list of SBOM version details under Output.

24. sbom_version_diff_get_batch

Batch retrieve diff information for multiple SBOM versions showing changes from predecessor versions.

Parameters

Returns: dict[str, Any] — per-version diff data (components, vulnerabilities, container findings changes) under Output.

25. vulnerability_get_prevalence

Get organizational prevalence data for specific vulnerabilities.

Parameters

Returns: dict[str, Any] — affected portfolios/applications/projects under Output.

26. vulnerability_get_details_batch

Get detailed information for multiple vulnerabilities by their IDs.

Parameters

Returns: dict[str, Any] — CVE/severity/affected-component details under Output.

Graphion — Infrastructure & Resource Inventory

27. service_account_list_and_retrieval

List and retrieve cloud accounts (service accounts) for the selected tenant.

Parameters

Returns: dict[str, Any] — cloud account list under Output, plus total, batch_size, batch_offset.

28. service_account_get_details

Retrieve detailed information for a specific cloud account (service account).

Parameters

Returns: dict[str, Any] — full cloud account configuration under Output.

29. service_account_list_resource_groups

List available Azure resource groups for a cloud account. Azure-only — raises if the account isn't Azure.

Parameters

Returns: dict[str, Any] — list of resource group names/IDs under Output.

30. resource_inventory_list

List cloud resources with rich filtering (e.g. "what resources are in this resource group").

Parameters

Returns: dict[str, Any] — Output (resource docs), total, batch_size, batch_offset.

31. resource_inventory_count

Get total resource count with optional filters (e.g. "how many resources are in this resource group?").

Parameters

Returns: dict[str, Any] — Output containing total_resources (int) and filters_applied (dict).

32. resource_change_list

List cloud resources whose configuration changed within a date window — change history, not current inventory. Requires GraphDB + tenant feature flag REIN_2601_B_RESOURCE_CHANGES_TREND.

Parameters

Returns: dict[str, Any] — Output (changed-resource records), total, batch_size, batch_offset.

33. resource_activity_timeline

Get the paginated change-history timeline for a single resource. Requires GraphDB + tenant feature flag REIN_2602_A_RESOURCE_DETAIL_VIEW.

Parameters

Returns: dict[str, Any] — Output (timeline events with history_id, changed_at, change_type), total, batch_size, batch_offset.

34. resource_activity_event_details

Get attribute-level details for 1 or 2 history events on a single resource (used to diff two events).

Parameters

Returns: dict[str, Any] — Output.events: list of {history_id, changed_at, change_type, changed_attributes}.

35. get_kubernetes_pod_resources

Query Kubernetes pod resources (EKS, AKS, GKE) from the resource inventory. Container image digests can be used to look up SBOM definitions via Graphion.

Parameters

Returns: dict[str, Any] — list of pod resources with container image details (inventory_id, resource_name, service_account_id, container status/image IDs); returned directly, not wrapped in Output.

36. resource_dependency_get

Given a resource (e.g., a VPC), return all dependent/related resources by traversing the inventory's metadata graph.

Parameters

Returns: dict[str, Any] — Output map of related resource types → details (IDs, names, types).

37. resource_list_by_schema

List resources of a specific type under a cloud account using the schema path category/component/resource (e.g. Network/VPC/VPC, Compute/EC2/Instances, Storage/S3/Buckets).

Parameters

Returns: dict[str, Any] — Output list of matching resources.

38. cloud_accounts_list

List all cloud accounts (service accounts) available in the current tenant.

Parameters

Returns: dict[str, Any] — Output list of cloud account IDs and names.

39. dashboard_infrastructure_summary

High-level summary combining org hierarchy with infrastructure — given a portfolio or application, returns associated projects, cloud accounts, and resource counts.

Parameters

Returns: dict[str, Any] — Output nested hierarchy: portfolio → applications → projects → cloud accounts → resource counts, plus total_portfolios, total_projects.

Graphion — Governance & Policy

40. policy_list_and_retrieval

Retrieve policy descriptions and metadata for given policy URIs.

Parameters

Returns: dict[str, Any] — Output: list of policy dicts (policy_id, name, uri, severity, classification, sub_classification, engine_type, scope, resource_type, resource_category, services, equivalent_policies), plus total.

41. policy_job_list_and_retrieval

Retrieve policy job execution details for specific policy job IDs.

Parameters

Returns: dict[str, Any] — Output: list of policy job details (execution result, violations, resource evaluations), plus total.

42. resource_violation_summary

Get a summary of infrastructure misconfiguration violations (guardrail policy violations), grouped by severity.

Parameters

Returns: dict[str, Any] — Output misconfiguration violation summary.

43. resource_vulnerability_summary

Get a summary of infrastructure vulnerabilities — counts and severity distribution.

Parameters

Returns: dict[str, Any] — Output vulnerability summary with severity breakdown.

44. resource_threat_summary

Get a summary of infrastructure security threats — real-time alerts, anomalous activity, posture findings.

Parameters

Returns: dict[str, Any] — Output threat summary.

45. infra_threat_list_and_details

List infrastructure threats for a cloud account and retrieve full details (list step chained internally to a batch-detail call).

Parameters

Returns: dict[str, Any] — Output list of threat details (severity, resource info, description, recommendation, remediation), plus total, batch_size, batch_offset.

Assessment (Well-Architected Framework)

Assessment — Well-Architected Framework

46. list_assessment_runs

Fetch and list details of assessment runs for specified assessment definitions.

Parameters

Returns: dict[str, Any] — {output: [<assessment run details>]}; may include Retrieved ids/Invalid ids if some inputs failed validation.

47. list_assessment_run_history

Fetch the details of history_ids of specified assessment runs by their IDs.

Parameters

Returns: dict[str, Any] — {Summary: {<rollup counts per run/history>}, Output: [<assessment run history objects>]}; may include Retrieved ids/Invalid ids.

48. get_policy_violations

Get a list of RecordIdentity objects for resources that have violated the given policy job.

Parameters

Returns: dict[str, Any] — {Output: [{"sysId": str, "lastUpdate": str, "table": str}]}.

49. list_assessment_questions

Get all the details of questions for the selected assessment runs history ids.

Parameters

Returns: dict[str, Any] — {Summary: {<per-run-id rollup>}, Output: [<question history objects>]}.

50. get_pillar_scores

Calculate the Well-Architected Framework scores for each pillar in a given assessment run.

Parameters

Returns: dict[str, Any] — dict keyed by framework_id → pillar_id → score (0–100). 0–33 = critical, 33–67 = moderate, 68–100 = excellent. Returned directly, not wrapped in Output.

51. submit_assessment_answer — Destructive

Answer a question or best practice — allows adding attachments, comments, and setting state.

Parameters

Returns: dict[str, Any] — API response with assessment run details and the list of answers per best_practice_id.

52. get_question_risk

Get the question-level risks of a specific assessment run.

Parameters

Returns: dict[str, Any] — {Output: {<risk summary by framework → pillar, with high/medium/low/no-risk counts and question_ids>}}.

53. list_assessment_definitions

Fetch one page of assessment definitions for the selected tenant (default page size 10). Results are paginated — the tool always tells the user how many were returned and offers to fetch the next page.

Parameters

Returns: str — paginated assessment definitions formatted as readable text; first line is a pagination note that must be relayed verbatim to the user.

54. list_frameworks

Retrieve the frameworks and details for the selected tenant.

Parameters

No parameters (besides the implicit session/auth context).

Returns: dict[str, Any] — {Summary: {<frameworks grouped by valid cloud service type, with id/name/description/version/valid_service_types/questions-by-pillar>}, Output: [<full framework objects>]}.

55. get_framework_questions

Retrieve questions for given question IDs.

Parameters

Returns: dict[str, Any] — {Output: [<question objects with details, best_practice_ids, timestamps>]}; may include Retrieved ids/Invalid ids.

56. get_best_practices

Fetch best practices for given system IDs.

Parameters

Returns: dict[str, Any] — {Summary: {<organized by framework → pillar → question, with num_practices, num_policies, manual/automated, risk levels, unique_policies>}, Output: [<full best practice objects, excluding "None of the above">]}; may include Retrieved ids/Invalid ids.

57. list_policy_descriptions

Retrieve policy descriptions for given policy URIs.

Parameters

Returns: dict[str, Any] — {Summary: {<grouped by severity, engine_type, scope, classification, sub_classification, resource_category, resource_type>}, Output: {policies: [...], count, success: True}}. Raises ValueError/RuntimeError.

58. get_related_policies

Retrieve and summarize all policies associated with a given framework (framework → questions → best practices → policies → policy descriptions).

Parameters

Returns: dict[str, Any] — shape depends on inputs: full grouped Summary (no args); {field: field_summary} (field only); {field: {specific_relation: {"Summary":..., "description":...}}} (both given/inferred); or a {"message":..., "Summary":...} warning if invalid.

59. get_policy_jobs

Retrieve policy job execution details for given policy job IDs.

Parameters

Returns: dict[str, Any] — {"job_details": [...], "count": int, "success": True} (list API response) or the API's dict directly (with success: True added if missing). Raises ValueError/RuntimeError.

60. get_policy_job

Retrieve detailed execution information for a single policy job.

Parameters

Returns: dict[str, Any] — detailed policy job execution info (with success: True added if missing). Raises ValueError/RuntimeError.

Workload

Workload

61. query_workload_resources

Execute a query against the ServiceResourceInventory collection given a WorkloadTierConfiguration (POST /v1/workload-query/execute then POST /v1/workload-query/resource/batch).

Parameters

Returns: dict[str, Any] — {Output: [<WorkloadResource objects with service_resource_id, service_account_id, category, resource_type, resource, resource_filter, operation_id, location, resource_name, tags, status, created_at, updated_at>]}; adds "Invalid filters" if unknown keys were supplied.

62. list_workload_definitions

Get a list of workload definitions for the selected tenant.

Parameters

Returns: dict[str, Any] — {Output: [<workload definition objects — name, description, timestamps, head/release version ids>]}.

63. create_workload — Destructive

Create a workload definition for the selected tenant (creates the definition, sets its state, creates a workload version, promotes it to a release version).

Parameters

Returns: dict[str, Any] — {sysId, createdOn, updatedOn, version, definition: {sysId, lastUpdate}, details: {tiers, tags}}; may include predecessor referencing a prior workload definition.

64. get_workload_version

Get details on a specific Workload Definition Version by id.

Parameters

Returns: dict[str, Any] — Workload Definition Version details, including ID, name, description, and associated workload definition metadata.

65. get_resource_batch

Batch-fetch full resource inventory details for one or more resource IDs — the canonical batch resource fetch (supersedes the former GET-by-id tool).

Parameters

Returns: dict[str, Any] — results keyed by resource ID, each with full details (configurations, tags, metadata, summary_details whose schema varies by resource type). Returns if the API result is falsy. Raises ValueError/RuntimeError.

66. list_resource_filters

Retrieve resource filter data for given service account IDs.

Parameters

Returns: list[dict[str, Any]] | None — resource filter data (categories, types, resource names), used to populate resource filter dropdowns / build create_workload's resource_filter. Returns None on an error or unexpected response type.

Common & Auth

Auth & Session

67. authenticate

Establish an authenticated CoreStack session. MUST be called before any other tool. Auto-selects the master account and tenant based on the user's last-used values.

Parameters

No parameters (besides the implicit session/auth context).

Returns: dict[str, Any] — {status: "fully_connected", message, master_account_id, master_account_name, tenant_id, tenant_name, available_master_account_ids: {id → name}}.

68. set_active_tenant

Switch the active tenant for all subsequent API calls. Requires authenticate to have run first.

Parameters

Returns: dict[str, Any] — {status: "tenant_reselected", tenant_name}.

69. set_master_account

Switch the active master account for all subsequent API calls. Only MCP-enabled master accounts are accepted.

Parameters

Returns: dict[str, Any] — {status: "account_selected", master_account_id, master_account_name, available_master_account_ids, available_tenant_ids}.

70. check_connection

Return the current CoreStack session state without raising errors. Safe to call at any time, including before authenticate.

Parameters

No parameters (besides the implicit session/auth context).

Returns: dict[str, Any] — {status: "connected"|"not_connected", message?, master_account_id, master_account_name, tenant_id, tenant_name, available_master_account_ids, available_tenant_ids}.

Agent & Chat

71. list_agent_types

Get agent types available to the given tenant.

Parameters

No parameters (besides the implicit session/auth context).

Returns: dict[str, Any] — agent types available to the tenant, under key agent_types.

72. list_chats

Get chat details based on the provided filtering criteria.

Parameters

Returns: dict[str, Any] — chat details batch matching the filter criteria.

73. list_conversations

Fetch the details of conversations for the specified chat based on the given filters.

Parameters

Returns: dict[str, Any] — retrieved conversations and their metadata.

74. send_agent_query — Destructive

Send a query to a CoreStack agent and return its response. Automatically creates a new chat for each request.

Parameters

Returns: dict[str, Any] — {output: <agent response data>}.

75. list_system_prompts

Retrieve the details of saved prompts matching the filtering criteria.

Parameters

Returns: dict[str, Any] — retrieved prompts + metadata; if some filters_agent_ids were invalid, shape is {output, retrieved_agent_ids, invalid_agent_ids}.

Bug Reporting (10)

76. file_bug — Destructive

File a Bug Report so the CoreStack team (or an AI fixer) can resolve it. Auto-attaches environment, request ID, tenant, master account, and user. Requires explicit user confirmation before filing.

Parameters

Returns: dict[str, Any] — {work_item_id, title, request_id, status: "created"}.

Frequently Asked Questions

Q: Do I need to call authenticate before every tool call?

No. Call authenticate once per session — every subsequent tool call reuses that session’s implicit auth context automatically. Re-authenticate only if the session expires or you need to switch master accounts.

Q: What happens if I don’t call set_active_tenant?

Tool calls run against the tenant that authenticate auto-selected based on your last-used values. If that isn’t the tenant you need, call set_active_tenant before making further calls — otherwise you may query the wrong tenant’s data.

Q: How do I know which tools will modify data instead of just reading it?

Check for the Destructive marker next to the tool name in Appendix A. Only four tools are marked Destructive — send_agent_query, file_bug, submit_assessment_answer, and create_workload. Every other tool is read-only.

Q: Can I use one session across FinOps, Graphion, Assessment, and Workload tools?

Yes. Tool domain doesn’t affect the session — once authenticated, you can call tools from any domain in the same session, as long as your role has access to that module.

Q: What does it mean when a parameter’s Required column says No but no default is listed?

Optional parameters without a stated default typically fall back to unset on the CoreStack backend, which usually means “don’t filter on this dimension.” Check the specific tool’s Description column in Appendix A — most optional parameters state their default explicitly.

Troubleshooting

Tool calls return a "not_connected" status

Cause: The session was never established, or it expired.

Solution:

1. Call authenticate again.

2. Confirm the response status is fully_connected.

3. Retry the original tool call.

If the issue persists, contact CoreStack support with your request_id (visible in most tool error responses), the tool name, and the timestamp of the failed call.

A tool call succeeds but returns data for the wrong tenant

Cause: The session’s active tenant was auto-selected from your last-used values, and doesn’t match the tenant you intended to query.

Solution:

1. Call check_connection to see the current tenant_id.

2. Call set_active_tenant with the correct tenant_id from available_tenant_ids.

3. Re-run the original tool call.

If the issue persists, contact CoreStack support with the tenant_id you expected, the tenant_id returned, and the tool name.

A Destructive tool call fails with a permissions error

Cause: Your assigned role doesn’t include Create/Update access for the module the tool belongs to.

Solution:

1. Confirm which role is assigned to your account under Settings > Roles.

2. Ask a Tenant Admin or Account Admin to grant the Create/Update access right for the relevant module.

3. Retry the tool call once the role change takes effect.

If the issue persists, contact CoreStack support with the tool name, your role name, and the exact error message returned.