fix(billing-cost-management): repair Savings Plans utilization and surface dropped RI metrics (#4580)

get_savings_plans_utilization read the wrong response member, returning no data;
details reported every plan at 0%. Both now pass the API response through.
get_reservation_utilization surfaces 9 dropped monetary fields. Removes four derived
keys contradicting the service's own aggregate.

Fixes #3351

Author: johnwangwyx

src/billing-cost-management-mcp-server/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Added AWS Billing preferences support via a read-only `get-billing-preferences` tool (`GetBillingPreferences`) reporting which member accounts participate in the Reserved Instance / Savings Plans discount pool and in credit sharing, whether newly created accounts join automatically, whether sharing is open, whether billing alerts are enabled, and the per-billing-period history of those settings. This is the only source for an account's discount-sharing state
 - Added AWS Billing Enterprise Support data via an `enterprise_support` tool (`GetEnterpriseSupportChargeSummary`, `GetEnterpriseSupportContractDetails`, `ListEnterpriseSupportLinkedAccountCharges`) covering a billing period's Enterprise Support charge and the Support-eligible spend it was calculated from, the contract terms that govern how the charge is allocated, and the per-linked-account charge breakdown
+- Added additional reservation cost and savings metrics to `get_reservation_utilization`: `on_demand_cost_of_ri_hours_used`, `net_ri_savings`, `total_potential_ri_savings`, `amortized_upfront_fee`, `amortized_recurring_fee`, `total_amortized_fee`, `ri_cost_for_unused_hours`, `realized_savings` and `unrealized_savings`.
 - Added AWS Billing credits support via a `credits` tool (`GetCredits`, `GetCreditAllocationHistory`) covering credit balance, expiration, product applicability, sharing configuration, and the per-service allocation ledger
 - Added AWS Compute Optimizer Automation support via a `compute-optimizer-automation` tool (`GetAutomationEvent`, `GetAutomationRule`, `GetEnrollmentConfiguration`, `ListAccounts`, `ListAutomationEvents`, `ListAutomationEventSteps`, `ListAutomationEventSummaries`, `ListAutomationRules`, `ListRecommendedActions`, `ListRecommendedActionSummaries`, `ListAutomationRulePreview`, `ListAutomationRulePreviewSummaries`, `ListTagsForResource`)
 - Extending support for Billing and Cost Management Pricing Calculator's Workload estimate (`CreateWorkloadEstimate`, `BatchCreateWorkloadEstimateUsage`).
@@ -26,6 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added an optional `context` parameter to the Cost Explorer `get_dimension_values` operation, so `SAVINGS_PLANS` returns values scoped to the plans an account owns rather than to its usage
 
 ### Fixed
+- Fixed `get_savings_plans_utilization` returning "No Savings Plans utilization data found" on every call (#3351). It read `SavingsPlansUtilizations` where the API returns `SavingsPlansUtilizationsByTime`, and behind that early return the figures were read from each row's top level as `{Amount, Unit}` mappings, but the API nests them under `Utilization`, `Savings` and `AmortizedCommitment` as decimal strings. Rows and `Total` now pass through as the API sends them, preserving decimal precision and the previously discarded blocks
+- Fixed `get_savings_plans_utilization_details` reporting every plan's utilization and savings as zero, from the same two causes. Rows now pass through as the API sends them, including the previously discarded `AmortizedCommitment` block and the whole of `Attributes` -- superseding the `summary` block, which read lowercase keys the API does not send, and exposing the owning `AccountId`
 - Corrected AWS Compute Optimizer recommendation response field names so EC2, Auto Scaling group, Lambda, and RDS tools return actual values instead of null. Fixed the shared savings-opportunity parser (`savingsOpportunityPercentage`), projected utilization metrics, EC2/RDS idle flags, nested ASG instance types, and the RDS instance/storage recommendation schema.
 - Corrected AWS Compute Optimizer ECS and Lambda recommendation response field names that read non-existent SDK fields and returned null. ECS now reads `currentPerformanceRisk`, `autoScalingConfiguration`, and `projectedUtilizationMetrics` (previously the non-existent `currentPerformance`, `autoScalingGroupArn`, and `projectedPerformance`), and Lambda derives the function name from the ARN (there is no `functionName` field).
 

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

@@ -477,4 +477,39 @@ def format_utilization_metrics(utilization_data: Dict) -> Dict:
             'UtilizationPercentageInUnits'
         ]
 
+    if 'OnDemandCostOfRIHoursUsed' in utilization_data:
+        formatted_utilization['on_demand_cost_of_ri_hours_used'] = utilization_data[
+            'OnDemandCostOfRIHoursUsed'
+        ]
+
+    if 'NetRISavings' in utilization_data:
+        formatted_utilization['net_ri_savings'] = utilization_data['NetRISavings']
+
+    if 'TotalPotentialRISavings' in utilization_data:
+        formatted_utilization['total_potential_ri_savings'] = utilization_data[
+            'TotalPotentialRISavings'
+        ]
+
+    if 'AmortizedUpfrontFee' in utilization_data:
+        formatted_utilization['amortized_upfront_fee'] = utilization_data['AmortizedUpfrontFee']
+
+    if 'AmortizedRecurringFee' in utilization_data:
+        formatted_utilization['amortized_recurring_fee'] = utilization_data[
+            'AmortizedRecurringFee'
+        ]
+
+    if 'TotalAmortizedFee' in utilization_data:
+        formatted_utilization['total_amortized_fee'] = utilization_data['TotalAmortizedFee']
+
+    if 'RICostForUnusedHours' in utilization_data:
+        formatted_utilization['ri_cost_for_unused_hours'] = utilization_data[
+            'RICostForUnusedHours'
+        ]
+
+    if 'RealizedSavings' in utilization_data:
+        formatted_utilization['realized_savings'] = utilization_data['RealizedSavings']
+
+    if 'UnrealizedSavings' in utilization_data:
+        formatted_utilization['unrealized_savings'] = utilization_data['UnrealizedSavings']
+
     return formatted_utilization

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

@@ -27,7 +27,7 @@
 )
 from ..utilities.logging_utils import get_context_logger
 from fastmcp import Context, FastMCP
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, Optional
 
 
 sp_performance_server = FastMCP(
@@ -234,7 +234,7 @@ async def get_savings_plans_utilization(
         )
 
         # Prepare the request parameters
-        request_params = {
+        request_params: Dict[str, Any] = {
             'TimePeriod': {'Start': start, 'End': end},
             'Granularity': granularity,
         }
@@ -243,147 +243,29 @@ async def get_savings_plans_utilization(
         if filter_expr:
             request_params['Filter'] = parse_json(filter_expr, 'filter')
 
-        # Use the paginate_aws_response utility for consistent pagination
-        all_utilizations, pagination_metadata = await paginate_aws_response(
-            ctx=ctx,
-            operation_name='GetSavingsPlansUtilization',
-            api_function=ce_client.get_savings_plans_utilization,
-            request_params=request_params,
-            result_key='SavingsPlansUtilizations',
-            token_param='NextToken',
-            token_key='NextToken',
-            max_pages=None,
-        )
-
-        # Check if we have any utilization data
-        if not all_utilizations:
-            await ctx_logger.warning(
-                'No Savings Plans utilization data found for the specified period'
-            )
-            return format_response(
-                'success',
-                {
-                    'savings_plans_utilizations': [],
-                    'pagination': pagination_metadata,
-                    'time_period': {'start': start, 'end': end},
-                    'granularity': granularity,
-                    'message': 'No Savings Plans utilization data found for the specified period. This could be because you do not have any active Savings Plans, or because the specified date range is outside your Savings Plans period.',
-                },
-            )
+        response = ce_client.get_savings_plans_utilization(**request_params)
 
-        # Format utilization data for better readability with proper default values
-        formatted_utilizations = []
-        for utilization in all_utilizations:
-            # Helper function to parse monetary values with defaults
-            def parse_monetary_value(key: str) -> Dict[str, Union[float, str]]:
-                value = utilization.get(key, {})
-                if not value or not isinstance(value, dict):
-                    return {'amount': 0.0, 'currency': 'USD', 'formatted': '0.0 USD'}
-
-                amount = value.get('Amount', 0.0)
-                # Handle numeric strings or None values
-                try:
-                    amount = float(amount) if amount is not None else 0.0
-                except (ValueError, TypeError):
-                    amount = 0.0
-
-                currency = value.get('Unit', 'USD')
-                return {
-                    'amount': amount,
-                    'currency': currency,
-                    'formatted': f'{amount} {currency}',
-                }
-
-            # Get time period with defaults
-            time_period = utilization.get('TimePeriod', {})
-            if not time_period:
-                time_period = {'Start': start, 'End': end}
-
-            # Get utilization percentage with default
-            utilization_pct = utilization.get('UtilizationPercentage')
-            if utilization_pct is None:
-                utilization_pct = 0.0
-            else:
-                try:
-                    utilization_pct = float(utilization_pct)
-                except (ValueError, TypeError):
-                    utilization_pct = 0.0
-
-            # Build formatted utilization with proper defaults
-            formatted_utilization = {
-                'time_period': time_period,
-                'total_commitment': parse_monetary_value('TotalCommitment'),
-                'used_commitment': parse_monetary_value('UsedCommitment'),
-                'unused_commitment': parse_monetary_value('UnusedCommitment'),
-                'utilization_percentage': utilization_pct,
-                'savings_plans_count': utilization.get('SavingsPlansCount', 0),
-            }
-            formatted_utilizations.append(formatted_utilization)
+        utilizations_by_time = response.get('SavingsPlansUtilizationsByTime', [])
+        total = response.get('Total')
 
-        # Format the response data
-        formatted_response = {
-            'savings_plans_utilizations': formatted_utilizations,
-            'pagination': pagination_metadata,
+        formatted_response: Dict[str, Any] = {
+            'savings_plans_utilizations': utilizations_by_time,
             'time_period': {'start': start, 'end': end},
             'granularity': granularity,
         }
 
-        # Add total utilization if available
-        try:
-            # We need to make one call to get the Total
-            initial_response = ce_client.get_savings_plans_utilization(**request_params)
-            if 'Total' in initial_response:
-                total = initial_response['Total']
-
-                # Parse total values with defaults
-                def parse_total_monetary_value(key: str) -> Dict[str, Union[float, str]]:
-                    value = total.get(key, {})
-                    if not value or not isinstance(value, dict):
-                        return {'amount': 0.0, 'currency': 'USD', 'formatted': '0.0 USD'}
-
-                    amount = value.get('Amount', 0.0)
-                    # Handle numeric strings or None values
-                    try:
-                        amount = float(amount) if amount is not None else 0.0
-                    except (ValueError, TypeError):
-                        amount = 0.0
-
-                    currency = value.get('Unit', 'USD')
-                    return {
-                        'amount': amount,
-                        'currency': currency,
-                        'formatted': f'{amount} {currency}',
-                    }
-
-                # Get utilization percentage with default
-                total_utilization_pct = total.get('UtilizationPercentage')
-                if total_utilization_pct is None:
-                    total_utilization_pct = 0.0
-                else:
-                    try:
-                        total_utilization_pct = float(total_utilization_pct)
-                    except (ValueError, TypeError):
-                        total_utilization_pct = 0.0
-
-                formatted_response['total'] = {
-                    'total_commitment': parse_total_monetary_value('TotalCommitment'),
-                    'used_commitment': parse_total_monetary_value('UsedCommitment'),
-                    'unused_commitment': parse_total_monetary_value('UnusedCommitment'),
-                    'utilization_percentage': total_utilization_pct,
-                }
-
-        except Exception as e:
-            # Log but don't fail if we can't get total
-            await ctx_logger.warning(f'Could not retrieve total utilization data: {str(e)}')
-            # Provide default total based on summing values if possible
-            if formatted_utilizations:
-                total_util_pct = sum(
-                    item['utilization_percentage'] for item in formatted_utilizations
-                ) / len(formatted_utilizations)
-                formatted_response['total'] = {
-                    'utilization_percentage': total_util_pct,
-                    'note': 'Estimated from individual utilization data',
-                }
+        if total is not None:
+            formatted_response['total'] = total
+
+        if not utilizations_by_time and total is None:
+            await ctx_logger.warning(
+                'No Savings Plans utilization data found for the specified period'
+            )
+            formatted_response['message'] = (
+                'No Savings Plans utilization data found for the specified period. This could be '
+                'because you do not have any active Savings Plans, or because the specified date '
+                'range is outside your Savings Plans period.'
+            )
 
         return format_response('success', formatted_response)
 
@@ -465,114 +347,13 @@ async def get_savings_plans_utilization_details(
                 },
             )
 
-        # Format utilization details for better readability
-        formatted_details = []
-        for detail in all_details:
-            # Helper function to parse monetary values with defaults
-            def parse_monetary_value(key: str) -> Dict[str, Union[float, str]]:
-                value = detail.get(key, {})
-                if not value or not isinstance(value, dict):
-                    return {'amount': 0.0, 'currency': 'USD', 'formatted': '0.0 USD'}
-
-                amount = value.get('Amount', 0.0)
-                # Handle numeric strings or None values
-                try:
-                    amount = float(amount) if amount is not None else 0.0
-                except (ValueError, TypeError):
-                    amount = 0.0
-
-                currency = value.get('Unit', 'USD')
-                return {
-                    'amount': amount,
-                    'currency': currency,
-                    'formatted': f'{amount} {currency}',
-                }
-
-            # Get utilization percentage with default
-            utilization_pct = detail.get('UtilizationPercentage')
-            if utilization_pct is None:
-                utilization_pct = 0.0
-            else:
-                try:
-                    utilization_pct = float(utilization_pct)
-                except (ValueError, TypeError):
-                    utilization_pct = 0.0
-
-            # Build formatted detail with proper defaults
-            formatted_detail = {
-                'savings_plan_arn': detail.get('SavingsPlanArn', ''),
-                'attributes': detail.get('Attributes', {}),
-                'utilization': {
-                    'total_commitment': parse_monetary_value('TotalCommitment'),
-                    'used_commitment': parse_monetary_value('UsedCommitment'),
-                    'unused_commitment': parse_monetary_value('UnusedCommitment'),
-                    'utilization_percentage': utilization_pct,
-                },
-                'savings': {
-                    'net_savings': parse_monetary_value('NetSavings'),
-                    'on_demand_cost_equivalent': parse_monetary_value('OnDemandCostEquivalent'),
-                    'amortized_upfront_fee': parse_monetary_value('AmortizedUpfrontFee'),
-                    'recurring_commitment': parse_monetary_value('RecurringCommitment'),
-                },
-            }
-
-            # Extract relevant information from attributes if available
-            if 'Attributes' in detail and detail['Attributes']:
-                attributes = detail['Attributes']
-
-                # Format and extract useful attribute information
-                region = attributes.get('region')
-                instance_family = attributes.get('instanceFamily')
-                savings_plan_type = attributes.get('savingsPlanType')
-
-                # Add formatted attribute info
-                if region or instance_family or savings_plan_type:
-                    formatted_detail['summary'] = {
-                        'region': region,
-                        'instance_family': instance_family,
-                        'savings_plan_type': savings_plan_type,
-                    }
-
-            formatted_details.append(formatted_detail)
-
-        # Format the response data
-        formatted_response = {
-            'savings_plans_utilization_details': formatted_details,
+        formatted_response: Dict[str, Any] = {
+            'savings_plans_utilization_details': all_details,
             'pagination': pagination_metadata,
             'time_period': {'start': start, 'end': end},
-            'total_count': len(formatted_details),
+            'total_count': len(all_details),
         }
 
-        # Add summary stats
-        if formatted_details:
-            try:
-                total_utilization = sum(
-                    detail['utilization']['utilization_percentage'] for detail in formatted_details
-                ) / len(formatted_details)
-                formatted_response['average_utilization_percentage'] = round(total_utilization, 2)
-
-                total_plans = len(formatted_details)
-                formatted_response['total_savings_plans'] = total_plans
-
-                # Calculate fully utilized plans (>95%)
-                fully_utilized = sum(
-                    1
-                    for detail in formatted_details
-                    if detail['utilization']['utilization_percentage'] >= 95.0
-                )
-                formatted_response['fully_utilized_plans'] = fully_utilized
-
-                # Calculate underutilized plans (<80%)
-                under_utilized = sum(
-                    1
-                    for detail in formatted_details
-                    if detail['utilization']['utilization_percentage'] < 80.0
-                )
-                formatted_response['under_utilized_plans'] = under_utilized
-
-            except Exception as e:
-                await ctx_logger.warning(f'Could not compute summary statistics: {str(e)}')
-
         return format_response('success', formatted_response)
 
     except Exception as e: