fix(billing-cost-management-mcp-server): refuse billing_view_arn where AWS ignores it (#4936)

GetSavingsPlansUtilization has no BillingViewArn request member (API
reference and botocore model), so cost-explorer dropped the argument
without saying so and returned utilization for the calling account's
primary billing view under the caller's requested view.

GetDimensionValues does take BillingViewArn, but in the RESERVATIONS and
SAVINGS_PLANS contexts AWS does not apply it: the values are the same as
without the view, including accounts outside it, and a well-formed ARN
that names no view is accepted. Only the COST_AND_USAGE context is scoped
to the view.

The tool now returns a validation_error with a hint in both cases, and
the description names the operations that accept billing_view_arn
(getDimensionValues in the COST_AND_USAGE context only) and the ones that
refuse it, instead of "most operations".

Author: finklen-amazon

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

@@ -263,10 +263,14 @@ def _with_example_dates(description: str) -> str:
   values present in the account.
 
 BILLING VIEW SUPPORT:
-Most Cost Explorer operations support an optional billing_view_arn parameter that allows you to scope
-your query to a specific billing view. If not provided, the query defaults to the account's primary
-billing view. You can use the list-billing-views and get-billing-view tools upon request to discover
-available billing views and their ARNs.
+billing_view_arn is accepted by getCostAndUsage, getCostAndUsageWithResources, getDimensionValues
+(COST_AND_USAGE context only), getCostForecast, getUsageForecast, getTagsOrValues and
+getCostCategories, and scopes the query to that billing view. If not provided, the query defaults
+to the account's primary billing view. getSavingsPlansUtilization (the AWS API has no billing view
+parameter) and getDimensionValues with context RESERVATIONS or SAVINGS_PLANS (AWS does not apply
+the view there) do not accept billing_view_arn; setting it returns a validation_error. You can use
+the list-billing-views and get-billing-view tools upon request to discover available billing views
+and their ARNs.
 
 Billing view types:
 - PRIMARY: Default view with all cost data for the account/org. Use for standard cost analysis.
@@ -331,7 +335,10 @@ async def cost_explorer(
         prediction_interval_level: Confidence level for forecasts
         tag_key: Tag key to get values for
         cost_category_name: Cost category to get values for
-        billing_view_arn: Optional ARN of a billing view to scope the query
+        billing_view_arn: Optional ARN of a billing view to scope the query. Rejected for
+            getSavingsPlansUtilization, whose API has no billing view parameter, and for
+            getDimensionValues with context RESERVATIONS or SAVINGS_PLANS, where AWS does not
+            apply the view
         context: The context for (getDimensionValues), which can be COST_AND_USAGE (the default),
             RESERVATIONS, or SAVINGS_PLANS. SAVINGS_PLANS scopes values to the plans an account owns.
 
@@ -427,6 +434,33 @@ async def cost_explorer(
                     ),
                 )
 
+            # In the RESERVATIONS and SAVINGS_PLANS contexts AWS accepts BillingViewArn but does
+            # not apply the view: the values are the same as without it, including accounts
+            # outside the view, and a well-formed ARN that names no view is not rejected. Refuse
+            # it rather than return unscoped values the caller believes are scoped to their view.
+            # Match the exact spelling: AWS rejects any other case of context on its own.
+            if billing_view_arn and context in ('RESERVATIONS', 'SAVINGS_PLANS'):
+                return format_response(
+                    'error',
+                    {
+                        'message': (
+                            'billing_view_arn is not supported for getDimensionValues with '
+                            f'context={context}: AWS does not apply the billing view in this '
+                            "context, so the values cover the calling account's own data (its "
+                            'primary billing view), including accounts outside the view.'
+                        )
+                    },
+                    error_type='validation_error',
+                    operation=operation,
+                    service=COST_EXPLORER_SERVICE_NAME,
+                    hint=(
+                        'Remove billing_view_arn to list the values for the calling '
+                        "account's own data, and say that they are not scoped to the requested "
+                        'view: they can include accounts the view does not cover. Do **NOT** '
+                        'retry with the same billing_view_arn.'
+                    ),
+                )
+
             return await get_dimension_values(
                 ctx,
                 ce_client,
@@ -515,6 +549,32 @@ async def cost_explorer(
             )
 
         elif operation == 'getSavingsPlansUtilization':
+            # GetSavingsPlansUtilization has no BillingViewArn, so the ARN cannot be sent.
+            # Refuse it: dropping it would return primary-view data the caller believes is
+            # scoped to their view.
+            if billing_view_arn:
+                return format_response(
+                    'error',
+                    {
+                        'message': (
+                            'billing_view_arn is not supported for getSavingsPlansUtilization: '
+                            'the GetSavingsPlansUtilization API has no billing view parameter, '
+                            "so it always reports the calling account's own data (its primary "
+                            'billing view).'
+                        )
+                    },
+                    error_type='validation_error',
+                    operation=operation,
+                    service=COST_EXPLORER_SERVICE_NAME,
+                    hint=(
+                        'Remove billing_view_arn to get Savings Plans utilization for the calling '
+                        "account's own data, and say that it is not scoped to the requested view: "
+                        'it can cover more accounts than the view (the whole organization when '
+                        'called from a management account). Do **NOT** retry with the same '
+                        'billing_view_arn.'
+                    ),
+                )
+
             return await get_savings_plans_utilization(
                 ctx, ce_client, start_date, end_date, granularity, filter
             )

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

@@ -2034,3 +2034,158 @@ async def test_description_states_savings_plans_data_lag():
     )
     assert 'an unknown SAVINGS_PLANS_TYPE matches nothing' in tool.description
     assert 'report that no data is available for that window (not zero)' in tool.description
+
+
+@pytest.mark.asyncio
+async def test_ce_get_savings_plans_utilization_rejects_billing_view_arn(
+    mock_context, sample_billing_view_arn
+):
+    """GetSavingsPlansUtilization has no BillingViewArn, so the tool refuses the ARN.
+
+    Dropping it would return utilization for the primary view labelled as the caller's view.
+    """
+    ce_mod = _reload_ce_with_identity_decorator()
+    real_fn = ce_mod.cost_explorer  # type: ignore
+
+    with (
+        patch.object(ce_mod, 'create_aws_client') as mock_create_client,
+        patch.object(ce_mod, 'get_savings_plans_utilization', new_callable=AsyncMock) as mock_impl,
+    ):
+        mock_create_client.return_value = MagicMock()
+
+        res = await real_fn(  # type: ignore
+            mock_context,
+            operation='getSavingsPlansUtilization',
+            start_date='2024-01-01',
+            end_date='2024-02-01',
+            granularity='MONTHLY',
+            billing_view_arn=sample_billing_view_arn,
+        )
+
+        assert res['status'] == 'error'
+        assert res['error_type'] == 'validation_error'
+        assert 'billing_view_arn' in res['message']
+        assert 'getSavingsPlansUtilization' in res['message']
+        assert 'billing_view_arn' in res['hint']
+        mock_impl.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_ce_get_savings_plans_utilization_empty_billing_view_arn_is_absent(mock_context):
+    """An empty billing_view_arn means no view, as for the operations that send it."""
+    ce_mod = _reload_ce_with_identity_decorator()
+    real_fn = ce_mod.cost_explorer  # type: ignore
+
+    with (
+        patch.object(ce_mod, 'create_aws_client') as mock_create_client,
+        patch.object(ce_mod, 'get_savings_plans_utilization', new_callable=AsyncMock) as mock_impl,
+    ):
+        mock_create_client.return_value = MagicMock()
+        mock_impl.return_value = {'status': 'success', 'data': {}}
+
+        res = await real_fn(  # type: ignore
+            mock_context,
+            operation='getSavingsPlansUtilization',
+            start_date='2024-01-01',
+            end_date='2024-02-01',
+            billing_view_arn='',
+        )
+
+        assert res['status'] == 'success'
+        mock_impl.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_description_names_billing_view_operations():
+    """The description names which operations take billing_view_arn and which refuse it."""
+    tool = await cost_explorer_server.get_tool('cost-explorer')
+    assert tool is not None and tool.description
+    description = ' '.join(tool.description.split())
+    assert 'Most Cost Explorer operations support an optional billing_view_arn' not in description
+    assert (
+        'billing_view_arn is accepted by getCostAndUsage, getCostAndUsageWithResources, '
+        'getDimensionValues (COST_AND_USAGE context only), getCostForecast, getUsageForecast, '
+        'getTagsOrValues and getCostCategories'
+    ) in description
+    assert (
+        'getSavingsPlansUtilization (the AWS API has no billing view parameter) and '
+        'getDimensionValues with context RESERVATIONS or SAVINGS_PLANS (AWS does not apply the '
+        'view there) do not accept billing_view_arn'
+    ) in description
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('context', ['RESERVATIONS', 'SAVINGS_PLANS'])
+async def test_ce_get_dimension_values_rejects_billing_view_arn_outside_cost_and_usage(
+    mock_context, sample_billing_view_arn, context
+):
+    """AWS does not apply a billing view to RESERVATIONS or SAVINGS_PLANS dimension values.
+
+    Sending the ARN would return unscoped values labelled as the caller's view.
+    """
+    ce_mod = _reload_ce_with_identity_decorator()
+    real_fn = ce_mod.cost_explorer  # type: ignore
+
+    with (
+        patch.object(ce_mod, 'create_aws_client') as mock_create_client,
+        patch.object(ce_mod, 'get_dimension_values', new_callable=AsyncMock) as mock_impl,
+    ):
+        mock_create_client.return_value = MagicMock()
+
+        res = await real_fn(  # type: ignore
+            mock_context,
+            operation='getDimensionValues',
+            dimension='LINKED_ACCOUNT',
+            context=context,
+            billing_view_arn=sample_billing_view_arn,
+        )
+
+        assert res['status'] == 'error'
+        assert res['error_type'] == 'validation_error'
+        assert 'billing_view_arn' in res['message']
+        assert f'context={context}' in res['message']
+        assert 'Do **NOT** retry with the same billing_view_arn' in res['hint']
+        assert context not in res['hint']  # the hint is fixed text; the context is in message
+        mock_impl.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    'context, billing_view_arn',
+    [
+        ('COST_AND_USAGE', 'arn:aws:billing::123456789012:billingview/custom-abc'),
+        ('SAVINGS_PLANS', None),
+        ('RESERVATIONS', ''),
+        ('savings_plans', 'arn:aws:billing::123456789012:billingview/custom-abc'),
+    ],
+)
+async def test_ce_get_dimension_values_billing_view_arn_allowed_cases(
+    mock_context, context, billing_view_arn
+):
+    """COST_AND_USAGE still sends the ARN; the other contexts run when no ARN is set.
+
+    A lowercase context goes to AWS unchanged, which rejects the context itself.
+    """
+    ce_mod = _reload_ce_with_identity_decorator()
+    real_fn = ce_mod.cost_explorer  # type: ignore
+
+    with (
+        patch.object(ce_mod, 'create_aws_client') as mock_create_client,
+        patch.object(ce_mod, 'get_dimension_values', new_callable=AsyncMock) as mock_impl,
+    ):
+        mock_create_client.return_value = MagicMock()
+        mock_impl.return_value = {'status': 'success', 'data': {'DimensionValues': []}}
+
+        res = await real_fn(  # type: ignore
+            mock_context,
+            operation='getDimensionValues',
+            dimension='LINKED_ACCOUNT',
+            context=context,
+            billing_view_arn=billing_view_arn,
+        )
+
+        assert res['status'] == 'success'
+        mock_impl.assert_awaited_once()
+        await_args = mock_impl.await_args
+        assert await_args is not None
+        assert await_args.args[-2:] == (billing_view_arn, context)