@@ -56,38 +56,38 @@
    - Helps identify RIs that could be modified or sold in the marketplace
 
 GROUPING get_reservation_coverage (group_by):
-GetReservationCoverage groups ONLY by these attributes:
+GetReservationCoverage groups ONLY by these attributes. Keys marked "only" apply just to
+that service (from the SERVICE filter, EC2 when omitted); others return a ValidationException:
 - AZ: Availability Zone (e.g. us-east-1a)
-- CACHE_ENGINE: ElastiCache engine (e.g. Redis, Memcached)
-- DATABASE_ENGINE: RDS database engine (e.g. PostgreSQL, MySQL, Aurora MySQL)
-- DEPLOYMENT_OPTION: deployment mode (e.g. Single-AZ, Multi-AZ)
+- CACHE_ENGINE: ElastiCache engine (e.g. Redis, Memcached). ElastiCache and MemoryDB only
+- DATABASE_ENGINE: RDS database engine (e.g. PostgreSQL, MySQL, Aurora MySQL). RDS only
+- DEPLOYMENT_OPTION: deployment mode (e.g. Single-AZ, Multi-AZ). RDS only
 - INSTANCE_TYPE: instance type (e.g. m4.xlarge, cache.r6g.large)
-- INVOICING_ENTITY: the Amazon entity that issues the invoice
+- INSTANCE_TYPE_FAMILY: instance family (e.g. m5, t3). EC2 only
 - LINKED_ACCOUNT: member account id in the organization
-- OPERATING_SYSTEM: operating system (e.g. Linux, Windows, RHEL)
-- PLATFORM: operating system / platform
+- PLATFORM: operating system / platform. EC2 only
 - REGION: AWS Region (e.g. us-east-1)
-- TENANCY: instance tenancy. Exact, case-sensitive values: Shared, Dedicated, Host
-SERVICE is NOT a valid group_by attribute here — grouping coverage by SERVICE
-returns a ValidationException. SERVICE is a FILTER dimension instead: pass it in
+- TENANCY: instance tenancy. Exact, case-sensitive values: Shared, Dedicated, Host. EC2 only
+SERVICE, INVOICING_ENTITY and OPERATING_SYSTEM are NOT valid group_by attributes here —
+grouping coverage by them returns a ValidationException. SERVICE is a FILTER dimension instead: pass it in
 `filter` (one SERVICE value per call; if you omit a SERVICE filter, Cost Explorer
 defaults to EC2), and call once per service to compare across services.
 Reservation coverage applies only to reservable services. The valid SERVICE
 filter values are "Amazon Elastic Compute Cloud - Compute" (the default when
-omitted), "Amazon Relational Database Service", "Amazon ElastiCache", and
-"Amazon Redshift". Use the full Cost Explorer service display name, not
+omitted), "Amazon Relational Database Service", "Amazon ElastiCache",
+"Amazon MemoryDB", "Amazon Redshift", "Amazon OpenSearch Service", and
+"Amazon Elasticsearch Service". Use the full Cost Explorer service display name, not
 "EC2"/"RDS".
 
 GROUPING get_reservation_utilization (group_by):
 GetReservationUtilization groups ONLY by SUBSCRIPTION_ID. No other attribute is
 valid. The SubscriptionId it returns (and that you filter on) is a NUMERIC id
 (e.g. "359809062"), not an ARN, instance id, or UUID — filtering SubscriptionId
-with an ARN/UUID returns no match.
+with an ARN/UUID returns a ValidationException ("must contain only digits").
 
 FILTERING (both operations): the Cost Explorer Expression supports only AND among
 dimensions and nests one level deep; multiple values for one dimension are OR'd.
-The SERVICE filter takes a single value and defaults to Amazon Elastic Compute
-Cloud - Compute when omitted.
+The SERVICE filter defaults to Amazon Elastic Compute Cloud - Compute when omitted.
 
 SCOPING LARGE QUERIES: a grouped or DAILY query over a wide window or many
 subscriptions can exceed the tool result size cap and return a ToolResultOversized
@@ -138,8 +138,8 @@ async def ri_performance(
         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. 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 as a JSON string. For coverage: AZ, CACHE_ENGINE, DATABASE_ENGINE, DEPLOYMENT_OPTION, INSTANCE_TYPE, INVOICING_ENTITY, LINKED_ACCOUNT, OPERATING_SYSTEM, PLATFORM, REGION, or TENANCY (SERVICE is NOT valid — filter on it instead). For utilization: SUBSCRIPTION_ID only.
-        filter: Optional filter as a JSON string (e.g., by service, region, or instance type). SERVICE takes a single value and defaults to EC2 when omitted; valid coverage SERVICE values are "Amazon Elastic Compute Cloud - Compute", "Amazon Relational Database Service", "Amazon ElastiCache", and "Amazon Redshift" (use the full display name, not "EC2"/"RDS"). SubscriptionId values are numeric, not ARNs/UUIDs. A wide grouped/DAILY query may exceed the result size cap (ToolResultOversized) — scope it with a filter, a shorter window, or MONTHLY granularity.
+        group_by: Optional grouping as a JSON string. For coverage: AZ, CACHE_ENGINE, DATABASE_ENGINE, DEPLOYMENT_OPTION, INSTANCE_TYPE, INSTANCE_TYPE_FAMILY, LINKED_ACCOUNT, PLATFORM, REGION, or TENANCY, depending on the service (see the tool description) (SERVICE is NOT valid — filter on it instead). For utilization: SUBSCRIPTION_ID only.
+        filter: Optional filter as a JSON string (e.g., by service, region, or instance type). SERVICE defaults to EC2 when omitted; valid coverage SERVICE values are "Amazon Elastic Compute Cloud - Compute", "Amazon Relational Database Service", "Amazon ElastiCache", "Amazon MemoryDB", "Amazon Redshift", "Amazon OpenSearch Service", and "Amazon Elasticsearch Service" (use the full display name, not "EC2"/"RDS"). SubscriptionId values are numeric, not ARNs/UUIDs. A wide grouped/DAILY query may exceed the result size cap (ToolResultOversized) — scope it with a filter, a shorter window, or MONTHLY granularity.
         sort_by: Optional sorting configuration as a JSON string with key and direction (ASCENDING or DESCENDING).
         max_items: Total number of groups to return across all pages. Omit it to fetch every
             page. Applies only to get_reservation_coverage with group_by set.
 
@@ -24,6 +24,7 @@
 
 import botocore.session
 import pytest
+import re
 from awslabs.billing_cost_management_mcp_server.tools.ri_performance_tools import (
     format_coverage_metrics,
     format_utilization_metrics,
@@ -33,6 +34,7 @@
 )
 from fastmcp import Context
 from fastmcp.tools import FunctionTool
+from typing import Dict
 from unittest.mock import AsyncMock, MagicMock, patch
 
 
@@ -186,7 +188,7 @@ def mock_ce_client():
                 'Groups': [
                     {
                         'Attributes': {
-                            'SUBSCRIPTION_ID': '012345678901-ec2-us-east-1-t3.large',
+                            'SUBSCRIPTION_ID': '359809062',
                         },
                         'Utilization': {
                             'UtilizationPercentage': '90.0',
@@ -197,7 +199,7 @@ def mock_ce_client():
                     },
                     {
                         'Attributes': {
-                            'SUBSCRIPTION_ID': '012345678901-rds-us-east-1-db.m5.large',
+                            'SUBSCRIPTION_ID': '359809070',
                         },
                         'Utilization': {
                             'UtilizationPercentage': '80.0',
@@ -481,8 +483,10 @@ async def test_get_reservation_coverage_with_options(
         )
 
         mock_metrics = ['CoverageHours', 'CoverageCost']
-        mock_group_by = [{'Type': 'DIMENSION', 'Key': 'SERVICE'}]
-        mock_filter = {'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon EC2']}}
+        mock_group_by = [{'Type': 'DIMENSION', 'Key': 'INSTANCE_TYPE'}]
+        mock_filter = {
+            'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute']}
+        }
         mock_sort_by = {'Key': 'CoverageHoursPercentage', 'SortOrder': 'DESCENDING'}
 
         mock_parse_json.side_effect = [mock_metrics, mock_group_by, mock_filter, mock_sort_by]
@@ -640,7 +644,9 @@ async def test_get_reservation_utilization_with_options(
         )
 
         mock_group_by = [{'Type': 'DIMENSION', 'Key': 'SUBSCRIPTION_ID'}]
-        mock_filter = {'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon EC2']}}
+        mock_filter = {
+            'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute']}
+        }
         mock_sort_by = {'Key': 'UtilizationPercentage', 'SortOrder': 'DESCENDING'}
 
         mock_parse_json.side_effect = [mock_group_by, mock_filter, mock_sort_by]
@@ -761,8 +767,8 @@ async def test_ri_performance_with_all_params(self, mock_context):
         """Test ri_performance with all parameters."""
         # Setup
         metrics = '["CoverageHours", "CoverageCost"]'
-        group_by = '[{"Type": "DIMENSION", "Key": "SERVICE"}]'
-        filter_expr = '{"Dimensions": {"Key": "SERVICE", "Values": ["Amazon EC2"]}}'
+        group_by = '[{"Type": "DIMENSION", "Key": "INSTANCE_TYPE"}]'
+        filter_expr = '{"Dimensions": {"Key": "SERVICE", "Values": ["Amazon Elastic Compute Cloud - Compute"]}}'
         sort_by = '{"Key": "CoverageHoursPercentage", "SortOrder": "DESCENDING"}'
 
         # Execute
@@ -1089,6 +1095,92 @@ async def test_description_says_when_total_is_returned():
     assert 'covers the whole query; it is not repeated' not in description
 
 
+# GetReservationCoverage GroupBy keys per SERVICE filter value, as the service validates
+# them (Service.coverageGroupByDims) and confirmed by live calls. The API reference and
+# botocore list one flat set that includes INVOICING_ENTITY and OPERATING_SYSTEM, which no
+# service accepts, and omits INSTANCE_TYPE_FAMILY.
+COVERAGE_GROUP_BY_BY_SERVICE = {
+    'Amazon Elastic Compute Cloud - Compute': {
+        'AZ',
+        'INSTANCE_TYPE',
+        'INSTANCE_TYPE_FAMILY',
+        'LINKED_ACCOUNT',
+        'PLATFORM',
+        'REGION',
+        'TENANCY',
+    },
+    'Amazon Relational Database Service': {
+        'AZ',
+        'INSTANCE_TYPE',
+        'LINKED_ACCOUNT',
+        'DATABASE_ENGINE',
+        'REGION',
+        'DEPLOYMENT_OPTION',
+    },
+    'Amazon ElastiCache': {'AZ', 'INSTANCE_TYPE', 'LINKED_ACCOUNT', 'CACHE_ENGINE', 'REGION'},
+    'Amazon MemoryDB': {'AZ', 'INSTANCE_TYPE', 'LINKED_ACCOUNT', 'CACHE_ENGINE', 'REGION'},
+    'Amazon Redshift': {'AZ', 'INSTANCE_TYPE', 'LINKED_ACCOUNT', 'REGION'},
+    'Amazon OpenSearch Service': {'AZ', 'INSTANCE_TYPE', 'LINKED_ACCOUNT', 'REGION'},
+    'Amazon Elasticsearch Service': {'AZ', 'INSTANCE_TYPE', 'LINKED_ACCOUNT', 'REGION'},
+}
+
+
+async def _ri_description() -> str:
+    tool = await ri_performance_server.get_tool('ri-performance')
+    assert tool is not None
+    return tool.description or ''
+
+
+# The "<scope> only" suffixes the coverage attribute list uses, and the services each names.
+COVERAGE_SCOPES = {
+    'EC2': {'Amazon Elastic Compute Cloud - Compute'},
+    'RDS': {'Amazon Relational Database Service'},
+    'ElastiCache and MemoryDB': {'Amazon ElastiCache', 'Amazon MemoryDB'},
+}
+
+
+def _documented_coverage_group_by(description: str) -> Dict[str, set]:
+    """Per service, the coverage attributes documented for it ("<scope> only" or every service)."""
+    block = description.split('GROUPING get_reservation_coverage (group_by):', 1)[1]
+    documented: Dict[str, set] = {service: set() for service in COVERAGE_GROUP_BY_BY_SERVICE}
+    for line in block.split('\n\n', 1)[0].splitlines():
+        match = re.match(r'- ([A-Z_]+): .*?(?:\. ([A-Za-z0-9 ]+) only)?$', line)
+        if match:
+            key, scope = match.groups()
+            for service in COVERAGE_SCOPES[scope] if scope else documented:
+                documented[service].add(key)
+    return documented
+
+
+@pytest.mark.asyncio
+async def test_description_lists_coverage_group_by_keys_per_service():
+    """Each service's documented coverage group_by keys equal the keys the service accepts."""
+    assert _documented_coverage_group_by(await _ri_description()) == COVERAGE_GROUP_BY_BY_SERVICE
+
+
+@pytest.mark.asyncio
+async def test_description_names_keys_no_service_accepts_for_coverage():
+    """SERVICE, INVOICING_ENTITY and OPERATING_SYSTEM are called out as invalid for every service."""
+    description = ' '.join((await _ri_description()).split())
+    assert (
+        'SERVICE, INVOICING_ENTITY and OPERATING_SYSTEM are NOT valid group_by attributes here'
+        in description
+    )
+    assert 'call once per service to compare across services' in description
+
+
+@pytest.mark.asyncio
+async def test_description_states_subscription_id_format_and_error():
+    """SubscriptionId is digits only; an ARN or UUID is rejected, not silently unmatched."""
+    description = ' '.join((await _ri_description()).split())
+    assert 'GetReservationUtilization groups ONLY by SUBSCRIPTION_ID' in description
+    assert 'is a NUMERIC id' in description
+    assert 'must contain only digits' in description
+    assert 'returns no match' not in description
+    # Utilization accepts several SERVICE values; only coverage caps them at 2.
+    assert 'SERVICE filter takes a single value' not in description
+
+
 @pytest.mark.asyncio
 async def test_ungrouped_utilization_ignores_max_items_and_next_token(mock_context):
     """GetReservationUtilization rejects any token without GroupBy, so none is sent."""