docs(billing-cost-management-mcp-server): warn that summing Cost Opti… (#4946)

* docs(billing-cost-management-mcp-server): warn that summing Cost Optimization Hub savings double-counts

The cost-optimization tool description said to focus on the highest estimated
savings but never said that list_recommendations items overlap, so an agent
that adds them up reports an inflated total. Commitment savings overlap with
rightsizing and idle actions on the same usage, Auto Scaling groups overlap
with their instances, Payer and Linked copies repeat, and
include_all_recommendations returns one row per term, payment option and
scope.

Add a SAVINGS TOTALS block that points to estimated_total_deduped_savings from
list_recommendation_summaries as the only de-duplicated total, and says it
stays comparable only with no filter or with accountIds and regions filters.
Filters on actionTypes, resourceTypes, implementationEfforts, restartNeeded
and rollbackPossible change how overlap is netted out, so filtered totals do
not sum to the portfolio total. Note the multi-row behavior in the
include_all_recommendations argument text, and add a test for the new text.

* docs(billing-cost-management-mcp-server): note summaries omit DatabaseSavingsPlans in savings totals guidance

list_recommendation_summaries totals and groups do not include
DatabaseSavingsPlans recommendations, while list_recommendations returns them.
Tell the model to add their savings from the list to the summary total, so a
reported portfolio total is not understated, and cover it in the description test.

---------

Co-authored-by: Som Chatterjee🤖 <somsubhr@amazon.com>

Author: somsubhro

src/billing-cost-management-mcp-server/awslabs/billing_cost_management_mcp_server/tools/cost_optimization_hub_tools.py

@@ -447,6 +447,22 @@ def _validate_order_by(
 key is case-sensitive; recommendations without the tag, or for a key that does not exist,
 are grouped under 'NoTagKey'.
 
+SAVINGS TOTALS:
+- For a portfolio total, use list_recommendation_summaries estimated_total_deduped_savings
+  with no filter, or with only accountIds and/or regions. Never add up list_recommendations
+  estimated_monthly_savings: items overlap (commitment purchases and rightsizing or idle
+  actions on the same usage, Auto Scaling groups and their instances, Payer and Linked copies).
+- Filters other than accountIds and regions (actionTypes, resourceTypes, implementationEfforts,
+  restartNeeded, rollbackPossible) change how overlap is netted out, so a filtered total is
+  not that slice's share of the portfolio total, and filtered totals do not sum to it.
+- list_recommendation_summaries totals and groups do not include DatabaseSavingsPlans
+  recommendations. list_recommendations returns them, so add their estimated_monthly_savings
+  to the summary total and say that the total was built that way.
+- Commitment (Savings Plans/Reserved Instance) savings assume current usage; implementing
+  rightsizing or idle recommendations reduces them.
+- With include_all_recommendations=true, the same purchase appears once per term, payment
+  option, and Payer/Linked scope, so a sum is inflated further.
+
 CRITICAL PARAMETER REQUIREMENTS:
 - 'filters' parameter must be passed as JSON string format
 - 'max_items' must be integer (not string)
@@ -598,8 +614,9 @@ async def cost_optimization_hub(
             omitted (default): one deduplicated recommendation per resource, and
             one Savings Plans/Reserved Instances purchase option per covered usage,
             chosen first by the account's commitment preference; Cost Optimization Hub
-            hides the alternatives. True: every recommendation,
-            including alternatives whose savings must not be added together.
+            hides the alternatives. True: every recommendation, including one row per
+            term, payment option, and Payer/Linked scope for the same purchase, so do
+            not sum their estimated_monthly_savings to get a total.
         next_token: Pagination token to resume from a previous response.
             Applies to list_recommendations, list_recommendation_summaries, and
             list_efficiency_metrics.

src/billing-cost-management-mcp-server/tests/tools/test_cost_optimization_hub_tools.py

@@ -1851,6 +1851,28 @@ async def test_coh_validation_exception_adds_valid_filter_values(mock_context, o
     assert 'Ec2Instance' in res['valid_filter_values']['resourceTypes']
 
 
+@pytest.mark.asyncio
+async def test_description_warns_that_summing_recommendation_savings_double_counts():
+    """The description names the one de-duplicated total and the filters that change it."""
+    from awslabs.billing_cost_management_mcp_server.tools import (
+        cost_optimization_hub_tools as coh_mod,
+    )
+
+    # Other tests reload the module with an identity decorator, which leaves no tool registered.
+    importlib.reload(coh_mod)
+    tool = await coh_mod.cost_optimization_hub_server.get_tool('cost-optimization')
+    assert tool is not None
+    description = ' '.join((tool.description or '').split())
+
+    assert 'SAVINGS TOTALS:' in description
+    assert 'estimated_total_deduped_savings' in description
+    assert 'Never add up list_recommendations estimated_monthly_savings' in description
+    for filter_name in ('actionTypes', 'resourceTypes', 'implementationEfforts'):
+        assert filter_name in description.split('SAVINGS TOTALS:')[1].split('CRITICAL')[0]
+    assert 'include_all_recommendations=true' in description
+    assert 'do not include DatabaseSavingsPlans' in description
+
+
 @pytest.mark.parametrize(
     'filters,expected',
     [