[CCR-3457] Document cost recommendations mcp tool

content/en/cloud_cost_management/cloud_cost_skill.md

@@ -95,9 +95,24 @@ After the initial summary, Bits Chat can:
 
 The [Datadog MCP Server][10] lets external AI agents query Datadog data. This is useful when you want to ask cost questions from an IDE, terminal-based assistant, or custom AI workflow.
 
-To use an external AI agent, [set up the Datadog MCP Server][11]. If your MCP client filters toolsets, include the `core` toolset to use the metric tools that can query Cloud Cost Management data.
+To use an external AI agent, [set up the Datadog MCP Server][11]. If your MCP client filters toolsets, you must enable the relevant toolset before the agent can call its tools:
 
-Cloud Cost Management data is available through the core metric tools:
+- Enable the `cost` toolset to list cost-saving recommendations with [`cost_recommendations`][16].
+- Enable the `core` toolset to query Cloud Cost Management metrics with the metric tools.
+
+### List cost-saving recommendations
+
+The `cost` toolset provides the [`cost_recommendations`][16] tool, which lists your organization's cost-saving recommendations ranked by estimated potential daily savings (highest first). It supports filtering by cloud provider, recommendation type, status, savings threshold, and resource tags. This tool requires the `Cloud Cost Management Read` permission.
+
+Example prompts for the `cost` toolset:
+
+- `What are my top cloud cost-saving recommendations?`
+- `How much could I save per day, and how many open recommendations do I have?`
+- `Show me open AWS recommendations for my Kubernetes clusters.`
+
+### Query Cloud Cost Management metrics
+
+The `core` toolset provides the metric tools that can query Cloud Cost Management data:
 
 | MCP tool                          | Usage                                 |
 | --------------------------------- | ------------------------------------- |
@@ -106,7 +121,7 @@ Cloud Cost Management data is available through the core metric tools:
 
 Ask your agent to set `use_cloud_cost` to `true` for Cloud Cost Management metrics, such as `all.cost`, `aws.cost.*`, `azure.cost.*`, `gcp.cost.*`, `oci.cost.*`, `custom.cost.*`, or `datadog.cost.*`. For observability metrics that explain a cost change, such as Kubernetes CPU or S3 bucket size, use the standard metric query behavior.
 
-Example prompts for MCP-connected agents:
+Example prompts for the `core` toolset:
 
 - `Use Datadog MCP to query cloud cost data. Set use_cloud_cost=true and show daily all.cost grouped by provider for the last 30 complete days.`
 - `Use get_datadog_metric_context with use_cloud_cost=true to find available tags for aws.cost.net.amortized.shared.resources.allocated, then group EC2 costs by team.`
@@ -133,3 +148,4 @@ For connection instructions, supported clients, and toolset configuration, see [
 [13]: /mcp_server/tools/#get_datadog_metric_context
 [14]: /mcp_server/tools/
 [15]: /notebooks/
+[16]: /mcp_server/tools/#cost_recommendations

content/en/cloud_cost_management/recommendations/_index.md

@@ -598,6 +598,8 @@ You can see the detailed logic for each recommendation type, along with observab
 
 Recommendations support [Tag Pipelines][11], allowing you to filter, group, and analyze recommendations using your organization's standardized tags. Any tag rules configured in Tag Pipelines are automatically applied to recommendations and [are normalized][12].
 
+You can also query your recommendations from an AI agent with the [`cost_recommendations`][16] tool in the Datadog MCP Server.
+
 ## Recommendation categories
 
 Below are the available cloud cost recommendation categories and their descriptions.
@@ -705,3 +707,4 @@ You can act on recommendations to save money and optimize costs. Cloud Cost Reco
 [13]: /bits_ai/bits_ai_dev_agent/setup
 [14]: /bits_ai/bits_ai_dev_agent/
 [15]: /cloud_cost_management/recommendations/cost_optimization_automation/
+[16]: /mcp_server/tools/#cost_recommendations

content/en/mcp_server/setup.md

@@ -626,6 +626,7 @@ These toolsets are generally available. See [Datadog MCP Server Tools][49] for a
 - `core`: The default toolset for logs, metrics, traces, dashboards, monitors, incidents, hosts, services, events, and notebooks
 - `alerting`: Tools for validating and creating monitors, searching monitor groups, retrieving monitor templates, analyzing monitor coverage, and searching SLOs
 - `cases`: Tools for [Case Management][42], including creating, searching, and updating cases; managing projects; and linking Jira issues
+- `cost`: Tools for [Cloud Cost Management][63], including listing cost-saving recommendations ranked by estimated potential daily savings
 - `dashboards`: Tools for retrieving, creating, updating, and deleting [dashboards][46], plus widget schema reference and validation
 - `dbm`: Tools for interacting with [Database Monitoring][33]
 - `ddsql`: Tools for querying Datadog data using [DDSQL][44], a SQL dialect with support for infrastructure resources, logs, metrics, RUM, spans, and other Datadog data sources
@@ -844,4 +845,5 @@ Local authentication is recommended for Cline and when remote authentication is
 [59]: https://chatgpt.com/
 [60]: https://www.datadoghq.com/product-preview/mcp-codexec/
 [61]: /getting_started/profiler/
-[62]: https://www.datadoghq.com/product-preview/datadog-agent-mcp/
+[62]: https://www.datadoghq.com/product-preview/datadog-agent-mcp/
+[63]: /cloud_cost_management/

content/en/mcp_server/tools.md

@@ -446,6 +446,21 @@ Searches for Datadog users by email, name, or handle. Useful for finding the rig
 
 - Find the Datadog user account for jane.doe@example.com.
 
+## Cloud Cost Management
+
+Tools for [Cloud Cost Management][64], including listing cost-saving recommendations ranked by estimated potential daily savings.
+
+### `cost_recommendations`
+*Toolset: **cost***\
+*Permissions Required: `Cloud Cost Management Read`*\
+Lists an organization's Cloud Cost Management cost-saving recommendations, ranked by estimated potential daily savings (highest first). Supports faceted filtering by cloud provider, recommendation type, status, savings threshold, and resource tags, along with pagination and a summary of the total count and total potential daily savings.
+
+#### Examples of queries:
+
+- What are my top cloud cost-saving recommendations?
+- How much could I save per day, and how many open recommendations do I have?
+- Which of our Kubernetes cluster optimizations does the team already have underway?
+
 ## Code Execution
 
 A single tool that runs agent-authored TypeScript in a Datadog-managed sandbox with direct access to Datadog APIs, for multi-signal investigation and ad-hoc data exploration in one call.
@@ -1579,3 +1594,4 @@ Adds an agent trigger to a workflow and publishes it, enabling the workflow to b
 [58]: /real_user_monitoring/
 [59]: /real_user_monitoring/rum_without_limits/
 [63]: /agent/guide/rshell/
+[64]: /cloud_cost_management/