# 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. **Note: **Every tool call runs inside an authenticated CoreStack session and inherits the caller’s assigned role permissions — the MCP server does not grant any access beyond what the calling user or service account already has in CoreStack. ## 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](https://docs.corestack.io/docs/mcp-client-configuration) 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. **Tip: **Start with read-only tools (for example, `get_cloud_accounts` or `list_assessment_definitions`) to confirm your session and permissions are correct before calling any Destructive tool. ## 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** | Parameter | Type | Description | Required | | ------------------------------ | -------------------------- | ------------------------------------------------------- | -------- | | filters | dict | QueryOperator filter tree, built via build_filter_query | Yes | | time_range_preset | str \| None | Preset time window | No | | start_date | str \| None | ISO-8601 UTC start; overrides preset | No | | end_date | str \| None | ISO-8601 UTC end; overrides preset | No | | group_by | list\[str \| dict] \| None | Dimension selectors | No | | billing_source | str | Cost metric key (default "raw_cost") | No | | billing_mode | bool \| None | Auto-derived from preset if omitted | No | | time_zone | str \| None | IANA timezone | No | | platform | str \| None | Only valid value is "kubernetes" | No | | limit | int | 0 = unlimited (default 0) | No | | skip_service_account_grouping | bool \| None | Auto-derived if omitted | No | | include_resource_children | bool | Default False | No | | auto_intersect_dimension_dates | bool | Clip dates to dimension's range (default True) | No | **Returns:** dict\[str, Any] — {Summary: {total_records}, Output: }. #### 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** | Parameter | Type | Description | Required | | ------------------- | -------------------------- | ------------------------------------------------- | -------- | | service_account_ids | list\[str] \| None | Scope lookup to specific accounts | No | | cloud_provider | CloudProviderFocus \| None | One of AWS/Azure/GCP/OCI, to scope display labels | No | **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** | Parameter | Type | Description | Required | | ----------------------------- | -------------------------- | ------------------------------------------------------ | -------- | | filters | dict | QueryOperator filter tree, via build_filter_query | Yes | | time_range_preset | str \| None | Preset time window | No | | start_date | str \| None | ISO-8601 UTC | No | | end_date | str \| None | ISO-8601 UTC | No | | time_zone | str \| None | IANA timezone | No | | platform | str \| None | Only "kubernetes" valid | No | | skip_service_account_grouping | bool \| None | Auto-derived if omitted | No | | billing_source | str | Cost metric key (default "raw_cost") | No | | group_by | list\[str \| dict] \| None | Dimension selectors | No | | limit | int | 0 = unlimited (default 0) | No | | billing_mode | bool \| None | Auto-derived from preset if omitted | No | | include_resource_children | bool | Default False | No | | granularity | int | Seconds; 86400 = daily (default 2592000, ≥1) | No | | compute_forecast | bool | Only supported for 14 specific presets (default False) | No | **Returns:** dict\[str, Any] — {Summary: {total_records}, output: []}. #### 4. `get_billing_usage_trend` Retrieves billing usage trends over time — resource consumption (GB, hours, API calls), not cost. **Parameters** | Parameter | Type | Description | Required | | ------------------- | ------------------- | ----------------------------- | -------- | | start_date | IsoDatetimeStr | ISO-8601 UTC | Yes | | end_date | IsoDatetimeStr | ISO-8601 UTC | Yes | | service_account_ids | list\[str] \| None | Scope to specific accounts | No | | group_by | list\[dict] \| None | Dimension selectors | No | | filters | dict \| None | QueryOperator filter tree | No | | granularity | int | Seconds (default 2592000, ≥1) | No | | time_zone | str \| None | IANA timezone | No | | limit | int | 0 = unlimited (default 0) | No | **Returns:** dict\[str, Any] — {summary: {total_records}, output: []}. #### 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** | Parameter | Type | Description | Required | | ------------------- | ------------------- | -------------------------------------------------------------- | -------- | | start_date | IsoDatetimeStr | ISO-8601 UTC | Yes | | end_date | IsoDatetimeStr | ISO-8601 UTC | Yes | | service_account_ids | list\[str] \| None | Scope to specific accounts | No | | group_by | list\[dict] \| None | Dimension selectors | No | | filters | dict \| None | QueryOperator filter tree | No | | granularity | int | Accepted but not forwarded (rate endpoint sets it server-side) | No | | time_zone | str \| None | IANA timezone | No | | limit | int | 0 = unlimited (default 0) | No | **Returns:** dict\[str, Any] — {summary: {total_records, undefined_rate_count}, output: []}. #### 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** | Parameter | Type | Description | Required | | ------------------------ | ---------------------- | --------------------------------------------------------- | -------- | | op | "AND"\|"OR"\|"NOT" | Boolean combination operator (default "AND") | No | | sub_filters | list\[dict] \| None | Pre-built QueryOperator dicts (2-level nesting) | No | | service_account_ids | list\[str] \| None | Scope to specific cloud accounts | No | | account_statuses | list\[Literal] \| None | active, inactive, not_onboarded, retired | No | | providers | list\[str] \| None | e.g. aws, azure, gcp, oci, snowflake, ... | No | | has_tags | bool \| None | Filter accounts by tag presence | No | | tag_keys | list\[str] \| None | Resource-level tag key presence | No | | tags | list\[dict] \| None | Resource-level {key, values, kind?} | No | | account_tag_keys | list\[str] \| None | Account-level tag key presence | No | | account_tag_key_values | list\[dict] \| None | {key, values} | No | | tenant_tag_key_values | list\[dict] \| None | {key, values} | No | | regions | list\[str] \| None | Cloud regions | No | | availability_zones | list\[str] \| None | Availability zones | No | | service_categories | list\[str] \| None | Service categories | No | | service_types | list\[str] \| None | Service types | No | | charge_types | list\[str] \| None | Charge types | No | | billing_entities | list\[str] \| None | Billing entities | No | | pricing_categories | list\[str] \| None | Pricing categories | No | | pricing_purchase_options | list\[str] \| None | Pricing purchase options | No | | product_families | list\[str] \| None | Product families | No | | product_service_codes | list\[str] \| None | Product service codes | No | | product_skus | list\[str] \| None | Product SKUs | No | | product_categories | list\[str] \| None | Product categories | No | | publishers | list\[str] \| None | Publishers | No | | meter_sub_categories | list\[str] \| None | Meter sub-categories | No | | resource_categories | list\[str] \| None | Resource categories | No | | resource_groups | list\[str] \| None | Resource groups | No | | resource_operations | list\[str] \| None | Resource operations | No | | field_presence | list\[dict] \| None | {field, has_field} | No | | k8s_extras | list\[dict] \| None | {key, values} | No | | tenant_ids | list\[str] \| None | Tenant IDs | No | | tenant_tag_keys | list\[str] \| None | Tenant tag key presence | No | | compartment_names | list\[str] \| None | OCI compartment names | No | | dimensions | list\[dict] \| None | {dimension_id, attribute, values} | No | | currencies | list\[str] \| None | ISO 4217; default \["USD"]; \[] disables currency scoping | No | **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** | Parameter | Type | Description | Required | | ----------------- | ---------------------- | ----------------------------------------------------------------------------------------- | -------- | | tenant_ids | list\[str] \| None | Omit for all tenants | No | | active_only | bool | Default True | No | | currency | str \| None | ISO 4217, default "USD"; None = all currencies | No | | include_tags | bool | Default False | No | | include_hierarchy | bool | Default False — nests tenants/providers/accounts | No | | include_fields | list\[Literal] \| None | Extra fields to merge in via batch call: is_active_in_cloud, custom_tags, onboarding_type | No | **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** | Parameter | Type | Description | Required | | ----------------- | ----------------------------- | ------------------------------------------------------- | -------- | | view | "list"\|"summary" \| None | Default "list" | No | | time_range_preset | str \| None | Preset time window | No | | start_date | str \| None | ISO-8601 UTC | No | | end_date | str \| None | ISO-8601 UTC | No | | cloud_account_ids | list\[str] \| None | Scope to specific accounts | No | | dimension_id | list\[str] \| None | Dimension sysId(s) | No | | billing_source | str \| None | Cost metric key | No | | currency | str \| None | Default "USD" | No | | status | list\[BudgetStatus] \| None | pending, in_progress, completed, expired, draft | No | | active_only | bool \| None | Shortcut for status=\['completed'] | No | | provider | list\[BudgetProvider] \| None | AWS, Azure, GCP, OCI | No | | budget_scope | BudgetScope \| None | tenant, cloud, custom, dimensions (applied client-side) | No | | frequency | BudgetFrequency \| None | Monthly, Quarterly, Annual, Weekly, Daily | No | | budget_engine | BudgetEngine \| None | Cloud_Native, System | No | | search | str \| None | Free-text search | No | **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** | Parameter | Type | Description | Required | | --------------- | ----------- | --------------------------------------- | -------- | | budget_id | str | 24-char hex MongoDB ObjectId | Yes | | budget_uri | str \| None | Needed to fetch threshold alert history | No | | include_history | bool | Default False | No | **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** | Parameter | Type | Description | Required | | ---------------- | ------------------ | ------------------------------------------------------------- | -------- | | project_id | list\[str] | Tenant/project IDs | Yes | | services | list\[str] \| None | Cloud providers | No | | term | int | 1 or 3 years (default 1) | No | | payment_option | str | No_Upfront, Partial_Upfront, All_Upfront (default No_Upfront) | No | | currency | str | Default "USD" | No | | page | int | Default 1 | No | | limit | int | Default 50 | No | | compute_forecast | bool | Default False | No | **Returns:** dict\[str, Any] — {Summary: {total_records}, Output: }. #### 11. `get_ri_reservation_coverage` Get reservation coverage for a specific RI — the percentage of eligible usage covered. **Parameters** | Parameter | Type | Description | Required | | ---------------- | ---- | --------------------------------------------------------------------------- | -------- | | cloud_account_id | str | 24-char hex | Yes | | reservation_id | str | UUID | Yes | | date_filter | str | mtd, last_month, last_3_months, last_6_months, ytd, last_year (default mtd) | No | **Returns:** dict\[str, Any] — {cloud_account_id, reservation_id, date_filter, Output: }. #### 12. `get_ri_reservation_utilization` Get utilization metrics for a specific RI — how much of the purchased capacity is actually used. **Parameters** | Parameter | Type | Description | Required | | ---------------- | ---- | -------------------------------------- | -------- | | cloud_account_id | str | 24-char hex | Yes | | reservation_id | str | UUID | Yes | | date_filter | str | Same options as coverage (default mtd) | No | **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** | Parameter | Type | Description | Required | | ----------- | ----------- | ---------------------------------------- | -------- | | date_filter | str | e.g. current_month, mtd, last_month, ... | Yes | | currency | str | Default "USD" | No | | service | str \| None | Cloud provider filter | No | **Returns:** dict\[str, Any] — {Summary: {total_records}, Output: []}. #### 14. `get_cost_optimization_by_types` Fetch cost optimization data from the executive-dashboard cost-optimization-by-types endpoint. **Parameters** | Parameter | Type | Description | Required | | ------------- | ------------ | --------------------- | -------- | | currency | str | Default "USD" | No | | deduplication | bool | Default False | No | | filter | dict \| None | Additional API filter | No | **Returns:** dict\[str, Any] — {"data": []}. #### 15. `get_right_sizing_recommendations` Fetch detailed right-sizing recommendations for a specific cloud account — current vs. recommended SKU per resource. **Parameters** | Parameter | Type | Description | Required | | ---------------- | ------------ | ---------------------------------------------------------------------------------------------------------------- | -------- | | cloud_account_id | str | 24-char hex | Yes | | currency | str | Default "USD" | No | | page | int | ≥0 (default 0) | No | | limit | int | 1–100 (default 10) | No | | search | str \| None | Free-text search | No | | filters | dict \| None | Keys: impact_level, optimization_type, resource_type, potential_cost_avoidance_from, potential_cost_avoidance_to | No | **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** | Parameter | Type | Description | Required | | ---------------- | --------------------------------- | ------------------------------------------------- | -------- | | cloud_account_id | str | 24-char hex | Yes | | request_type | RecommendationRequestType \| None | idle, orphaned, right_size, config (default idle) | No | | provider | RecommendationProvider | AWS, Azure, GCP, OCI (default AWS) | No | | currency | str | Default "USD" | No | | resource_status | str \| None | open, closed, rejected (default open) | No | | page | int | ≥1 (default 1) | No | | limit | int | 1–100 (default 10) | No | **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** | Parameter | Type | Description | Required | | -------------- | ------------------------------ | ------------------------------------------------------------- | -------- | | provider | list\[SavingsProvider] \| None | AWS, Azure, GCP, OCI; omit = all | No | | term | SavingsTerm \| None | "1" or "3" years (default "1") | No | | payment_option | SavingsPaymentOption \| None | No_Upfront, Partial_Upfront, All_Upfront (default No_Upfront) | No | | currency | Currency \| None | Default USD | No | **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** | Parameter | Type | Description | Required | | ------------------- | ------------------ | -------------------------- | -------- | | service_account_ids | list\[str] \| None | Scope to specific accounts | No | | batch_size | int | 0–500 (default 50) | No | | batch_offset | int | ≥0 (default 0) | No | **Returns:** dict\[str, Any] — {Summary: {total_records}, output: {plans: [], total, page, page_size}}. #### 19. `get_savings_plans_utilization` Fetch paginated utilization time-series for a single purchased savings plan. **Parameters** | Parameter | Type | Description | Required | | ------------------- | ------------------ | ------------------------------ | -------- | | plan_id | str | From get_savings_plans_details | Yes | | service_account_ids | list\[str] \| None | Scope to specific accounts | No | | start_date | str \| None | ISO-8601 | No | | end_date | str \| None | ISO-8601 | No | | batch_size | int | 0–500 (default 50) | No | | batch_offset | int | ≥0 (default 0) | No | **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** | Parameter | Type | Description | Required | | ------------------- | ------------------ | -------------------------- | -------- | | service_account_ids | list\[str] \| None | Scope to specific accounts | No | **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** | Parameter | Type | Description | Required | | ------------------- | --------------------- | ----------------------------------------- | -------- | | time_range_preset | str \| None | Preset time window | No | | start_date | str \| None | ISO-8601 UTC | No | | end_date | str \| None | ISO-8601 UTC, exclusive | No | | service_account_ids | list\[str] \| None | Scope to specific accounts | No | | currency | str \| None | ISO 4217; omit = all currencies | No | | anomaly_status | AnomalyStatus \| None | active, rejected | No | | filters | dict \| None | QueryOperator tree (limited operator set) | No | **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** | Parameter | Type | Description | Required | | ------------------- | ------------------ | ------------------------------------------ | -------- | | time_range_preset | str \| None | Preset time window | No | | start_date | str \| None | ISO-8601 UTC | No | | end_date | str \| None | ISO-8601 UTC | No | | service_account_ids | list\[str] \| None | Scope to specific accounts | No | | currency | str \| None | ISO 4217 | No | | filters | dict \| None | Adds product_families, resource_id support | No | | top_n | int | 1–100 (default 10) | No | **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** | Parameter | Type | Description | Required | | ----------------- | --------------------- | ----------------------------------- | -------- | | currency | str | Default "USD" | No | | time_range_preset | str \| None | Preset time window | No | | start_date | str \| None | ISO-8601 UTC | No | | end_date | str \| None | ISO-8601 UTC | No | | anomaly_status | AnomalyStatus \| None | active, rejected | No | | dimension_ids | list\[str] \| None | Omit = all dimensions | No | | filters | dict \| None | Adds DimensionQueryOperator support | No | **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** | Parameter | Type | Description | Required | | ---------- | ---- | ------------------ | -------- | | batch_size | int | 1–100 (default 10) | No | **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** | Parameter | Type | Description | Required | | ------------------------ | ----------------------------- | ------------------------------- | -------- | | search | str \| None | Search portfolios by name | No | | name | list\[str] \| None | Filter by exact portfolio names | No | | tags | list\[dict\[str,str]] \| None | \[{"key":..,"value":..}] | No | | filter_sbom_names | list\[str] \| None | Filter by SBOM names | No | | filter_application_ids | list\[str] \| None | Filter by application IDs | No | | filter_application_names | list\[str] \| None | Filter by application names | No | | sbom_filter | str \| None | e.g. with_sbom | No | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | total | int | 0 = all (default 0) | No | | sort_column | str | Default "updated_at" | No | | sort_ascending | bool | Default False | No | **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** | Parameter | Type | Description | Required | | ------------ | ---- | ----------- | -------- | | portfolio_id | str | 24-char hex | Yes | **Returns:** dict\[str, Any] — complete portfolio details under Output. #### 3. `application_list_and_retrieval` List and retrieve applications for the selected tenant. **Parameters** | Parameter | Type | Description | Required | | -------------------- | ----------------------------- | ----------------------- | -------- | | search | str \| None | Search by name | No | | name | list\[str] \| None | Exact application names | No | | owner | list\[str] \| None | Owner names/emails | No | | tags | list\[dict\[str,str]] \| None | Tag filter | No | | filter_portfolio_ids | list\[str] \| None | Portfolio IDs | No | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | total | int | 0 = all (default 0) | No | | sort_column | str | Default "updated_at" | No | | sort_ascending | bool | Default False | No | **Returns:** dict\[str, Any] — list of application details under Output. #### 4. `application_get_details` Retrieve detailed information for a specific application. **Parameters** | Parameter | Type | Description | Required | | -------------- | ---- | ----------- | -------- | | application_id | str | 24-char hex | Yes | **Returns:** dict\[str, Any] — complete application details under Output. #### 5. `project_list_and_retrieval` List and retrieve projects for the selected tenant. **Parameters** | Parameter | Type | Description | Required | | ----------------------------- | ----------------------------- | -------------------- | -------- | | search | str \| None | Search by name | No | | name | list\[str] \| None | Exact project names | No | | owner | list\[str] \| None | Owner names/emails | No | | tags | list\[dict\[str,str]] \| None | Tag filter | No | | filter_portfolio_ids | list\[str] \| None | Portfolio IDs | No | | filter_portfolio_names | list\[str] \| None | Portfolio names | No | | filter_Graphion_project_ids | list\[str] \| None | Project IDs | No | | filter_Graphion_project_names | list\[str] \| None | Project names | No | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | total | int | 0 = all (default 0) | No | | sort_column | str | Default "updated_at" | No | | sort_ascending | bool | Default False | No | **Returns:** dict\[str, Any] — list of project details under Output. #### 6. `project_get_details` Retrieve detailed information for a specific project. **Parameters** | Parameter | Type | Description | Required | | ---------- | ---- | ----------- | -------- | | project_id | str | 24-char hex | Yes | **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** | Parameter | Type | Description | Required | | -------------- | ---------- | ---------------------------- | -------- | | definition_ids | list\[str] | Max 1000, each a 24-char hex | Yes | **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** | Parameter | Type | Description | Required | | --------------------------- | ----------------------------- | --------------------------------------------------------------------------- | -------- | | search | str \| None | Search by name/description/tags | No | | tags | list\[dict\[str,str]] \| None | Tag filter | No | | filters_query_operator | dict \| None | Advanced QueryOperator; takes precedence over the convenience filters below | No | | filter_portfolio_ids | list\[str] \| None | Portfolio IDs | No | | filter_application_ids | list\[str] \| None | Application IDs | No | | filter_Graphion_project_ids | list\[str] \| None | Project IDs | No | | filter_inventory_ids | list\[str] \| None | Mapped resource inventory IDs (24-char hex) | No | | filter_container_digests | list\[str] \| None | Mapped container image sha256 digests (64-char hex) | No | | filter_service_account_ids | list\[str] \| None | Scopes resource-mapping filter to cloud accounts | No | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | total | int | 0 = all (default 0) | No | | sort_column | str | Default "updated_at" | No | | sort_ascending | bool | Default False | No | **Returns:** dict\[str, Any] — list of SBOM definition details under Output. #### 9. `sbom_get_details` Retrieve detailed information for a specific SBOM definition. **Parameters** | Parameter | Type | Description | Required | | ------------------ | ---- | ----------- | -------- | | sbom_definition_id | str | 24-char hex | Yes | **Returns:** dict\[str, Any] — complete SBOM definition details under Output. #### 10. `sbom_version_get_details` Retrieve detailed information for a specific SBOM version. **Parameters** | Parameter | Type | Description | Required | | ---------- | ---- | ----------- | -------- | | version_id | str | 24-char hex | Yes | **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** | Parameter | Type | Description | Required | | ------------------ | ---- | ----------- | -------- | | sbom_definition_id | str | 24-char hex | Yes | **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** | Parameter | Type | Description | Required | | ----------------------- | ------------------ | ---------------------------------------------------------------------------------------------- | -------- | | filter_sbom_version_ids | list\[str] \| None | Scope to specific SBOM versions | No | | filters_query_operator | dict \| None | Advanced QueryOperator (severity, category, execution phase, status); overrides simple filters | No | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | total | int | 0 = all (default 0) | No | | sort_column | str | Default "updated_at" | No | | sort_ascending | bool | Default False | No | **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** | Parameter | Type | Description | Required | | ----------- | ---------- | ------------------- | -------- | | finding_ids | list\[str] | 24-char hex strings | Yes | **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** | Parameter | Type | Description | Required | | ------------ | ------------ | ----------------------- | -------- | | list_context | dict \| None | Pagination/sort context | No | **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** | Parameter | Type | Description | Required | | -------------------------- | ------------ | ----------------------- | -------- | | vulnerable_components_only | bool | Default False | No | | list_context | dict \| None | Pagination/sort context | No | **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** | Parameter | Type | Description | Required | | ------------ | ------------ | ----------------------- | -------- | | list_context | dict \| None | Pagination/sort context | No | **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** | Parameter | Type | Description | Required | | -------------------- | ------------------------- | ------------------------------------------------------------------- | -------- | | categories | list\[str] \| None | Security categories; defaults to \["vulnerability"] | No | | days_range | str \| None | 0-30 days, 31-60 days, 61-90 days, 91-365 days, > 365 days, Unknown | No | | all_version | bool | Consider all versions vs. latest only (default False) | No | | group_by_application | bool | Default False | No | | sbom_version_ids | list\[str] \| str \| None | Restrict to specific SBOM version(s) | No | | list_context | dict \| None | Pagination/sort context | No | **Returns:** dict\[str, Any] — top 10 prioritized issues under Output. #### 18. `dashboard_vulnerabilities_by_component` Get aggregated vulnerability counts grouped by component properties. **Parameters** | Parameter | Type | Description | Required | | -------------- | ------------ | ----------------------------- | -------- | | aggregation_by | str | One of product, kev, severity | Yes | | list_context | dict \| None | Pagination/sort context | No | **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** | Parameter | Type | Description | Required | | ------------ | ------------ | ------------------------------------------------- | -------- | | start_date | str \| None | ISO format; defaults to 90 days ago | No | | end_date | str \| None | ISO format; defaults to today | No | | granularity | str | day, week, month, quarter, year (default "month") | No | | list_context | dict \| None | Pagination/sort context | No | **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** | Parameter | Type | Description | Required | | ------------ | ------------ | ----------------------- | -------- | | start_date | str \| None | Defaults to 90 days ago | No | | end_date | str \| None | Defaults to today | No | | list_context | dict \| None | Pagination/sort context | No | **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** | Parameter | Type | Description | Required | | ------------------ | ----------- | ---------------------------------------------------- | -------- | | version_id | str | Primary SBOM version ID (24-char hex) | Yes | | compare_version_id | str \| None | If omitted, compares against the predecessor version | No | **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** | Parameter | Type | Description | Required | | ------------- | ---------- | -------------------------- | -------- | | component_ids | list\[str] | Max 1000, 24-char hex each | Yes | **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** | Parameter | Type | Description | Required | | ----------- | ---------- | -------------------------- | -------- | | version_ids | list\[str] | Max 1000, 24-char hex each | Yes | **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** | Parameter | Type | Description | Required | | ----------- | ---------- | -------------------------- | -------- | | version_ids | list\[str] | Max 1000, 24-char hex each | Yes | **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** | Parameter | Type | Description | Required | | ----------------- | ------------------ | -------------------------------------- | -------- | | vulnerability_ids | list\[str] | 24-char hex strings | Yes | | tenant_ids | list\[str] \| None | Defaults to the current session tenant | No | **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** | Parameter | Type | Description | Required | | ----------------- | ---------- | -------------------------- | -------- | | vulnerability_ids | list\[str] | Max 1000, 24-char hex each | Yes | **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** | Parameter | Type | Description | Required | | --------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | search | str \| None | Regex match on account name | No | | statuses | list\[str] \| None | e.g. \["active"], \["inactive"] | No | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | sort_column | str | Default "Name" | No | | sort_ascending | bool | Default True | No | | include_fields | list\[str] \| None | Extra batch-detail fields; default \['name','native_details','status']; valid: name, is_active_in_cloud, native_details, status, currency, custom_tags, onboarding_type | No | | cloud_native_id | str \| None | Native cloud identifier (Azure sub GUID, AWS account ID, GCP project ID) to resolve — bypasses normal listing when set | No | **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** | Parameter | Type | Description | Required | | ------------------ | ---- | ----------- | -------- | | service_account_id | str | 24-char hex | Yes | **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** | Parameter | Type | Description | Required | | ------------------ | ---- | ------------------------------------- | -------- | | service_account_id | str | 24-char hex, must be an Azure account | Yes | **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** | Parameter | Type | Description | Required | | --------------- | ------------------- | ---------------------------------- | -------- | | cloud_account | list\[dict] \| None | \[{"id": service_account_id}, ...] | No | | resource_filter | str \| None | Resource group / filter name | No | | category | str \| None | e.g. Network, Storage, Compute | No | | component | str \| None | e.g. EC2, VPC | No | | resource_type | str \| None | Maps to the resource field | No | | location | str \| None | Cloud region/zone | No | | search | str \| None | Search by name | No | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | sort_column | str | Default "updated_at" | No | | sort_ascending | bool | Default False | No | **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** | Parameter | Type | Description | Required | | --------------- | ------------------- | ---------------------------------- | -------- | | cloud_account | list\[dict] \| None | \[{"id": service_account_id}, ...] | No | | resource_filter | str \| None | Resource group / filter name | No | | category | str \| None | Resource category | No | | location | str \| None | Cloud region/zone | No | **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** | Parameter | Type | Description | Required | | ------------------- | ------------------ | --------------------------------------------- | -------- | | tenant_id | str | 24-char hex | Yes | | start_date | str | ISO-8601 | Yes | | end_date | str \| None | Defaults to start_date (single-day window) | No | | change_statuses | list\[str] \| None | new, modified, deleted, discovered, unchanged | No | | service_account_ids | list\[str] \| None | 24-char hex | No | | categories | list\[str] \| None | e.g. \["Compute","Network"] | No | | search | str \| None | Free-text over name/id/type | No | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | **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** | Parameter | Type | Description | Required | | ------------------ | ------------------ | ----------------------------------- | -------- | | tenant_id | str | 24-char hex | Yes | | resource_id | str | Provider-native resource identifier | Yes | | resource_category | str | e.g. Compute, Network | Yes | | resource_type | str | e.g. Instances | Yes | | resource | str | e.g. EC2, VPC | Yes | | start_date | str \| None | Defaults to now − 90 days | No | | end_date | str \| None | Defaults to now | No | | change_type_filter | list\[str] \| None | e.g. \["modified","deleted"] | No | | batch_size | int | Default 25 | No | | batch_offset | int | Default 0 | No | **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** | Parameter | Type | Description | Required | | ----------------- | ---------- | -------------------------------------------------------- | -------- | | tenant_id | str | 24-char hex | Yes | | resource_id | str | Provider-native resource identifier | Yes | | resource_category | str | e.g. Compute, Network | Yes | | resource_type | str | e.g. Instances | Yes | | resource | str | e.g. EC2, VPC | Yes | | event_ids | list\[str] | 1 or 2 history_id values from resource_activity_timeline | Yes | **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** | Parameter | Type | Description | Required | | ------------------- | ----------- | ------------------------------- | -------- | | service_account_ids | list\[str] | Cloud account IDs (24-char hex) | Yes | | cluster_name | str \| None | Partial match | No | | pod_name | str \| None | Partial match | No | | namespace | str \| None | Kubernetes namespace | No | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | **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** | Parameter | Type | Description | Required | | --------------------- | ---- | ----------- | -------- | | resource_inventory_id | str | 24-char hex | Yes | **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** | Parameter | Type | Description | Required | | ------------------ | ----------- | ----------------------------------------------- | -------- | | service_account_id | str | 24-char hex | Yes | | category | str | e.g. Network, Compute, Storage | Yes | | component | str | e.g. VPC, EC2, S3 | Yes | | resource | str | e.g. VPC, Subnets, Instances, Buckets | Yes | | resource_filter | str \| None | Additional scope filter (region/resource group) | No | **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** | Parameter | Type | Description | Required | | ------------ | ----------- | ---------------------------------------- | -------- | | service_name | str \| None | Filter by provider, e.g. AWS, Azure, GCP | No | **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** | Parameter | Type | Description | Required | | -------------- | ----------- | --------------------------------------------------------------------- | -------- | | portfolio_id | str \| None | 24-char hex (at least one of portfolio_id/application_id recommended) | No | | application_id | str \| None | 24-char hex | No | **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** | Parameter | Type | Description | Required | | ----------- | ---------- | ---------------------------------------- | -------- | | policy_uris | list\[str] | e.g. "CS.AWS.Audit.EC2.EncryptionAtRest" | Yes | **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** | Parameter | Type | Description | Required | | -------------- | ---------- | ----------- | -------- | | policy_job_ids | list\[str] | 24-char hex | Yes | **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** | Parameter | Type | Description | Required | | ------------------- | ------------------ | ------------------------------------------------------------------- | -------- | | service_account_ids | list\[str] \| None | Filter to specific cloud accounts; default = all accounts in tenant | No | **Returns:** dict\[str, Any] — Output misconfiguration violation summary. #### 43. `resource_vulnerability_summary` Get a summary of infrastructure vulnerabilities — counts and severity distribution. **Parameters** | Parameter | Type | Description | Required | | ------------------- | ------------------ | --------------------------------- | -------- | | service_account_ids | list\[str] \| None | Filter to specific cloud accounts | No | **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** | Parameter | Type | Description | Required | | ------------------- | ------------------ | --------------------------------- | -------- | | service_account_ids | list\[str] \| None | Filter to specific cloud accounts | No | **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** | Parameter | Type | Description | Required | | ------------------ | ----------- | ----------------------------------------------------------------------------------- | -------- | | service_account_id | str | 24-char hex cloud account ID | Yes | | search | str \| None | Free-text search across resource name/id/type, alert ID, findings type, description | No | | batch_size | int | Default 20 | No | | batch_offset | int | Default 0 | No | **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** | Parameter | Type | Description | Required | | ------------------------- | ---------- | ---------------------------- | -------- | | assessment_definition_ids | list\[str] | Assessment definition sysIds | Yes | **Returns:** dict\[str, Any] — {output: []}; 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** | Parameter | Type | Description | Required | | ------------------ | ----------- | ---------------------------------------------------- | -------- | | assessment_run_ids | list\[dict] | \[{"sysId": str, "lastUpdate"?: str, "table"?: str}] | Yes | **Returns:** dict\[str, Any] — {Summary: {}, Output: []}; 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** | Parameter | Type | Description | Required | | ------------------------- | ---- | -------------------------------- | -------- | | assessment_run_history_id | str | ID of the assessment run history | Yes | | policy_job_id | str | ID of the policy job | Yes | **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** | Parameter | Type | Description | Required | | -------------------------- | ----------- | ---------------------------------------------------- | -------- | | assessment_run_history_ids | list\[dict] | \[{"sysId": str, "lastUpdate"?: str, "table"?: str}] | Yes | **Returns:** dict\[str, Any] — {Summary: {}, Output: []}. #### 50. `get_pillar_scores` Calculate the Well-Architected Framework scores for each pillar in a given assessment run. **Parameters** | Parameter | Type | Description | Required | | ----------------- | ---- | ------------------------------- | -------- | | assessment_run_id | str | System ID of the assessment run | Yes | **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. **Warning:** This tool creates or modifies data in CoreStack. Confirm the inputs before calling it. **Parameters** | Parameter | Type | Description | Required | | ------------------- | ------------------ | ------------------------------------------- | -------- | | assessment_run_id | str | ID of the assessment run | Yes | | framework_id | str | ID of the framework | Yes | | pillar_id | str | ID of the pillar | Yes | | question_id | str | ID of the question | Yes | | best_practice_id | str | ID of the best practice | Yes | | created_by | str | User who created the answer | Yes | | owner | str | Owner of the answer | Yes | | assigned_to | list\[str] \| None | Users assigned to the answer | No | | attachment_ids | list\[str] \| None | Attachment IDs | No | | comment_id | str \| None | ID of the comment | No | | comment | str \| None | Comment text | No | | recommendation | str \| None | Recommendation text | No | | sync_failure_reason | str \| None | Reason for sync failure | No | | status | str | Default "Open" | No | | created_on | str \| None | ISO timestamp; defaults to current UTC time | No | **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** | Parameter | Type | Description | Required | | ----------------- | ---- | ------------------------ | -------- | | assessment_run_id | str | ID of the assessment run | Yes | **Returns:** dict\[str, Any] — {Output: {}}. #### 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** | Parameter | Type | Description | Required | | -------------- | ---- | --------------------------------------- | -------- | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | total | int | Default 0 | No | | sort_column | str | Default "UpdatedOn" | No | | sort_ascending | bool | Default False | No | | query_type | str | Default "AssessmentQueryAssessmentName" | No | | query_name | str | Default "" | No | **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: {}, Output: []}. #### 55. `get_framework_questions` Retrieve questions for given question IDs. **Parameters** | Parameter | Type | Description | Required | | ------------ | ----------- | --------------------------------------------------------------------------- | -------- | | question_ids | list\[dict] | \[{"sysId": str, "lastUpdate"?: str, "table"?: str}] from framework pillars | Yes | **Returns:** dict\[str, Any] — {Output: []}; may include Retrieved ids/Invalid ids. #### 56. `get_best_practices` Fetch best practices for given system IDs. **Parameters** | Parameter | Type | Description | Required | | ----------------- | ----------- | ------------------------------------------------------------------- | -------- | | best_practice_ids | list\[dict] | \[{"sysId": str, "lastUpdate"?: str, "table"?: str}] from questions | Yes | **Returns:** dict\[str, Any] — {Summary: {}, Output: []}; may include Retrieved ids/Invalid ids. #### 57. `list_policy_descriptions` Retrieve policy descriptions for given policy URIs. **Parameters** | Parameter | Type | Description | Required | | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------- | | policy_uris | list\[str] | Policy URIs. URIs with disallowed schemes (http\://, file://) or targets (localhost, 169.254., metadata.google.internal) are rejected | Yes | **Returns:** dict\[str, Any] — {Summary: {}, 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** | Parameter | Type | Description | Required | | ----------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | framework_id | str | ID of the framework | Yes | | field | str | Classification field to group/filter by: severity, resource_type, resource_category, engine_type, scope, classification, sub_classification (default "") | No | | specific_relation | str | Specific classification value within field (e.g. EC2, EBS); can be given without/with an incorrect field — the tool infers the correct field (default "") | No | **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** | Parameter | Type | Description | Required | | -------------- | ---------- | -------------- | -------- | | policy_job_ids | list\[str] | Policy job IDs | Yes | **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** | Parameter | Type | Description | Required | | ------------- | ---- | ------------- | -------- | | tenant_id | str | Tenant ID | Yes | | policy_job_id | str | Policy job ID | Yes | **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** | Parameter | Type | Description | Required | | -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------- | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | total | int | Default 0 | No | | sort_column | str | CloudAccountName, Cloud, ResourceID, ResourceCategory, ResourceType, Resource, ResourceRegion (default "CloudAccountName") | No | | sort_ascending | bool | Default True | No | | filters | dict \| None | Maps to WorkloadTierConfiguration: name, description, owner, cloud_account_id, resource_filter (maps to ServiceResourceFilter) | No | **Returns:** dict\[str, Any] — {Output: []}; adds "Invalid filters" if unknown keys were supplied. #### 62. `list_workload_definitions` Get a list of workload definitions for the selected tenant. **Parameters** | Parameter | Type | Description | Required | | -------------- | ------------ | ------------------ | -------- | | batch_size | int | Default 10 | No | | batch_offset | int | Default 0 | No | | total | int | Default 0 | No | | sort_column | str | Default "Name" | No | | sort_ascending | bool | Default True | No | | filter_query | dict \| None | Additional filters | No | **Returns:** dict\[str, Any] — {Output: []}. #### 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). **Warning:** This tool creates or modifies data in CoreStack. Confirm the inputs before calling it. **Parameters** | Parameter | Type | Description | Required | | ------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------- | | name | str | Name of the workload definition | Yes | | description | str | Description | Yes | | workload_type | str | Type of the workload definition | Yes | | attachments | list\[str] \| None | Attachment IDs | No | | owner | str \| None | Defaults to the current user's ID if omitted/invalid | No | | is_active | bool | Default True | No | | tiers | list\[Tier] \| None | Tiers composing the workload: each Tier = {name, description?, owner?, cloud_account_id: list[str], resource_filter: list[dict]} | No | | tags | list\[Tag] \| None | \[{"key": str, "value": str}] | No | **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** | Parameter | Type | Description | Required | | ---------- | ---- | ------------------------------------------------------- | -------- | | version_id | str | Must match the Workload Definition Version UUID pattern | Yes | **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** | Parameter | Type | Description | Required | | ------------ | ---------- | ------------------------ | -------- | | resource_ids | list\[str] | Resource IDs to retrieve | Yes | **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** | Parameter | Type | Description | Required | | ------------------- | ---------- | ----------------------------------------------- | -------- | | service_account_ids | list\[str] | Service account IDs to get resource filters for | Yes | **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** | Parameter | Type | Description | Required | | --------- | ---- | ------------------------------------------------------------------------------- | -------- | | tenant_id | str | Tenant ID, taken from available_tenant_ids (from authenticate/check_connection) | Yes | **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** | Parameter | Type | Description | Required | | ----------------- | ---- | ------------------------------------ | -------- | | master_account_id | str | ID from available_master_account_ids | Yes | **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** | Parameter | Type | Description | Required | | --------------- | ----------- | -------------------------------------- | -------- | | filter_agent_id | str | Agent ID to filter chats by | Yes | | batch_size | int | Page size (default 10) | No | | batch_offset | int | Pagination offset (default 0) | No | | total | int | Total to retrieve; 0 = all (default 0) | No | | sort_column | str | Column to sort by (default "Name") | No | | sort_ascending | bool | Sort ascending (default True) | No | | filter_name | str \| None | Chat name filter | No | **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** | Parameter | Type | Description | Required | | -------------- | ---- | --------------------------------------- | -------- | | filter_chat_id | str | Chat ID to filter by | Yes | | batch_size | int | Page size (default 10) | No | | batch_offset | int | Pagination offset (default 0) | No | | total | int | Total to retrieve; 0 = all (default 0) | No | | sort_column | str | Column to sort by (default "CreatedAt") | No | | sort_ascending | bool | Sort ascending (default True) | No | **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. **Warning:** This tool creates or modifies data in CoreStack. Confirm the inputs before calling it. **Parameters** | Parameter | Type | Description | Required | | --------- | ---- | ----------------------------------- | -------- | | agent_id | str | Agent sys_id, from list_agent_types | Yes | | query | str | The user's query text | Yes | **Returns:** dict\[str, Any] — {output: }. #### 75. `list_system_prompts` Retrieve the details of saved prompts matching the filtering criteria. **Parameters** | Parameter | Type | Description | Required | | ------------------- | ------------------ | --------------------------------------- | -------- | | filters_agent_ids | list\[str] | Agent IDs to filter prompts by | Yes | | filters_prompt_type | str | Prompt type filter (default "default") | No | | filters_prompt | str \| None | Prompt name filter | No | | tags | list\[Tag] \| None | Tag filter, \[{"key":..,"value":..}] | No | | batch_size | int | Page size (default 10) | No | | batch_offset | int | Pagination offset (default 0) | No | | total | int | Total to retrieve; 0 = all (default 0) | No | | sort_column | str | Column to sort by (default "CreatedAt") | No | | sort_ascending | bool | Sort ascending (default True) | No | **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. **Warning:** This tool creates or modifies data in CoreStack. Confirm the inputs before calling it. **Parameters** | Parameter | Type | Description | Required | | ----------------------- | ----------- | ---------------------------------------------------------- | -------- | | user_confirmed | bool | Must be True; only set after explicit user confirmation | Yes | | title | str | Short bug title | Yes | | summary | str | One-paragraph description, including affected product area | Yes | | repro_steps | str \| None | Numbered repro steps | No | | expected_behavior | str \| None | What should happen | No | | actual_behavior | str \| None | What actually happened | No | | conversation_transcript | str \| None | Relevant chat turns/errors | No | | error_details | str \| None | Stack traces / error messages / failing tool names | No | **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.