fix(ri/sp-performance): omit Granularity when GroupBy is set (#4479)

Cost Explorer's GetReservationCoverage, GetReservationUtilization, and
GetSavingsPlansCoverage treat Granularity and GroupBy as mutually
exclusive. The coverage/utilization request builders always set
Granularity, so any grouped query failed with a deterministic
ValidationException (e.g. 'Granularity is not supported when specifying
groupBy').

Send Granularity only when the request is not grouped, across
get_reservation_coverage, get_reservation_utilization, and
get_savings_plans_coverage. Document the mutual exclusivity in both tool
descriptions and granularity docstrings so the agent avoids sending both.

Update tests to assert Granularity is omitted when GroupBy is present.

Author: wangyuhere

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

@@ -60,7 +60,12 @@
 - SERVICE: AWS service (EC2, RDS, etc.)
 - TENANCY: Instance tenancy (default, dedicated)
 
-Reservation utilization can only be grouped by SUBSCRIPTION_ID.""",
+Reservation utilization can only be grouped by SUBSCRIPTION_ID.
+
+IMPORTANT: `granularity` and `group_by` are mutually exclusive. If `group_by` is
+provided, `granularity` is ignored (the Cost Explorer API does not allow both for
+GetReservationCoverage or GetReservationUtilization). Provide one or the other,
+not both.""",
 )
 async def ri_performance(
     ctx: Context,
@@ -81,7 +86,7 @@ async def ri_performance(
         operation: The operation to perform: 'get_reservation_coverage' or 'get_reservation_utilization'
         start_date: Start date in YYYY-MM-DD format (inclusive). Defaults to 30 days ago if not provided.
         end_date: End date in YYYY-MM-DD format (exclusive). Defaults to today if not provided.
-        granularity: Time granularity of the data (DAILY or MONTHLY). Defaults to DAILY.
+        granularity: Time granularity of the data (DAILY or MONTHLY). Defaults to DAILY. Ignored when group_by is provided (granularity and group_by are mutually exclusive).
         metrics: List of metrics to retrieve for coverage as a JSON string (e.g., '["HoursCoverage", "CostCoverage"]'). Defaults to all metrics.
         group_by: Optional grouping of results as a JSON string. For coverage, supports multiple dimensions. For utilization, only supports SUBSCRIPTION_ID.
         filter: Optional filter to apply to the results as a JSON string, such as filtering by service, region, or instance type.
@@ -174,9 +179,8 @@ async def get_reservation_coverage(
         )
 
         # Prepare the request parameters
-        request_params = {
+        request_params: Dict[str, Any] = {
             'TimePeriod': {'Start': start, 'End': end},
-            'Granularity': granularity,
         }
 
         # Add optional parameters if provided
@@ -186,6 +190,13 @@ async def get_reservation_coverage(
         if group_by:
             request_params['GroupBy'] = parse_json(group_by, 'group_by')
 
+        # GetReservationCoverage treats Granularity and GroupBy as mutually
+        # exclusive: "Granularity is not supported when specifying groupBy".
+        # Only send Granularity when the request is not grouped, otherwise the
+        # API returns a ValidationException.
+        if not group_by:
+            request_params['Granularity'] = granularity
+
         if filter_expr:
             request_params['Filter'] = parse_json(filter_expr, 'filter')
 
@@ -295,15 +306,21 @@ async def get_reservation_utilization(
         )
 
         # Prepare the request parameters
-        request_params = {
+        request_params: Dict[str, Any] = {
             'TimePeriod': {'Start': start, 'End': end},
-            'Granularity': granularity,
         }
 
         # Add optional parameters if provided
         if group_by:
             request_params['GroupBy'] = parse_json(group_by, 'group_by')
 
+        # GetReservationUtilization treats Granularity and GroupBy as mutually
+        # exclusive: "If GroupBy is set, Granularity can't be set". Only send
+        # Granularity when the request is not grouped, otherwise the API returns
+        # a ValidationException.
+        if not group_by:
+            request_params['Granularity'] = granularity
+
         if filter_expr:
             request_params['Filter'] = parse_json(filter_expr, 'filter')
 

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

@@ -44,7 +44,12 @@
 
 1. get_savings_plans_coverage: Shows how much of your eligible usage is covered by Savings Plans
 2. get_savings_plans_utilization: Shows overall utilization metrics for your Savings Plans
-3. get_savings_plans_utilization_details: Shows detailed per-Savings Plan utilization""",
+3. get_savings_plans_utilization_details: Shows detailed per-Savings Plan utilization
+
+IMPORTANT: For get_savings_plans_coverage, `granularity` and `group_by` are mutually
+exclusive. If `group_by` is provided, `granularity` is ignored (the Cost Explorer
+GetSavingsPlansCoverage API does not allow both). Valid `group_by` dimensions for
+coverage are SERVICE, REGION, or INSTANCE_FAMILY.""",
 )
 async def sp_performance(
     ctx: Context,
@@ -64,7 +69,7 @@ async def sp_performance(
         operation: The operation to perform: 'get_savings_plans_coverage', 'get_savings_plans_utilization', or 'get_savings_plans_utilization_details'
         start_date: Start date in YYYY-MM-DD format (inclusive). Defaults to 30 days ago if not provided.
         end_date: End date in YYYY-MM-DD format (exclusive). Defaults to today if not provided.
-        granularity: Time granularity of the data (DAILY or MONTHLY). Defaults to DAILY.
+        granularity: Time granularity of the data (DAILY or MONTHLY). Defaults to DAILY. For coverage, ignored when group_by is provided (granularity and group_by are mutually exclusive).
         metrics: List of metrics to retrieve as a JSON string. For coverage, only 'SpendCoveredBySavingsPlans' is valid.
         group_by: Optional grouping of results as a JSON string. For coverage, supports SERVICE, REGION, or INSTANCE_FAMILY.
         filter: Optional filter to apply to the results as a JSON string.
@@ -145,13 +150,18 @@ async def get_savings_plans_coverage(
         # Prepare the request parameters
         request_params = {
             'TimePeriod': {'Start': start, 'End': end},
-            'Granularity': granularity,
             'Metrics': metrics_list,
         }
 
-        # Add optional parameters if provided
+        # Add optional parameters if provided.
+        # GetSavingsPlansCoverage treats Granularity and GroupBy as mutually
+        # exclusive: "Granularity can't be set if GroupBy is set". Only send
+        # Granularity when the request is not grouped, otherwise the API returns
+        # a ValidationException.
         if group_by:
             request_params['GroupBy'] = parse_json(group_by, 'group_by')
+        else:
+            request_params['Granularity'] = granularity
 
         if filter_expr:
             request_params['Filter'] = parse_json(filter_expr, 'filter')

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

@@ -407,6 +407,9 @@ async def test_get_reservation_coverage_with_options(
         assert request_params['Filter'] == mock_filter
         assert request_params['SortBy'] == mock_sort_by
         assert request_params['MaxResults'] == 50
+        # Granularity and GroupBy are mutually exclusive for GetReservationCoverage:
+        # when GroupBy is set, Granularity must not be sent.
+        assert 'Granularity' not in request_params
 
         assert result['status'] == 'success'
 
@@ -550,6 +553,9 @@ async def test_get_reservation_utilization_with_options(
         assert request_params['Filter'] == mock_filter
         assert request_params['SortBy'] == mock_sort_by
         assert request_params['MaxResults'] == 50
+        # Granularity and GroupBy are mutually exclusive for GetReservationUtilization:
+        # when GroupBy is set, Granularity must not be sent.
+        assert 'Granularity' not in request_params
 
         assert result['status'] == 'success'
 

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

@@ -627,7 +627,9 @@ async def test_get_savings_plans_coverage_with_options(
         assert request_params['Metrics'] == mock_metrics
         assert request_params['GroupBy'] == mock_group_by
         assert request_params['Filter'] == mock_filter
-        assert request_params['Granularity'] == 'MONTHLY'
+        # Granularity and GroupBy are mutually exclusive for GetSavingsPlansCoverage:
+        # when GroupBy is set, Granularity must not be sent.
+        assert 'Granularity' not in request_params
 
         assert result['status'] == 'success'