docs(billing-cost-management-mcp-server): document Not in the sp-recommendation filter (#4920)

GetSavingsPlansPurchaseRecommendation accepts a Not expression around the
LINKED_ACCOUNT Dimensions filter, which is how a caller excludes accounts
from a recommendation. The filter arg doc said only that AND and OR are not
supported, so a caller could not tell that Not works.

- filter arg doc: a LINKED_ACCOUNT Dimensions expression, optionally wrapped
  in a single Not to exclude those accounts, with a one-line example;
  MatchOptions, if given, must be EQUALS; And, Or and a Not inside another
  Not are rejected. The parameter type is unchanged. The internal helper
  filter_expr doc says the same in short.
- Test: the served filter description carries the Not wording, a parseable
  example, the MatchOptions rule and the rejected forms.

Co-authored-by: Junaid Girkar <60307291+junaidgirkar@users.noreply.github.com>

Author: finklen-amazon

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

@@ -114,9 +114,12 @@ async def sp_recommendation(
             LIGHT/MEDIUM/HEAVY_UTILIZATION values, which are Reserved Instance utilization levels and do not apply to Savings Plans.
         lookback_period_in_days: SEVEN_DAYS, THIRTY_DAYS, or SIXTY_DAYS. Required for get_savings_plans_purchase_recommendation.
         account_scope: PAYER or LINKED.
-        filter: Filter recommendations by Account ID. Includes Dimensions only,
-            with Key as LINKED_ACCOUNT and Value one or more Account IDs. AND and OR operators are
-            not supported. Applies to get_savings_plans_purchase_recommendation only.
+        filter: Filter recommendations by Account ID: a Dimensions expression with Key
+            LINKED_ACCOUNT and Values one or more Account IDs, optionally wrapped in a single Not to
+            exclude those accounts, for example
+            {"Not": {"Dimensions": {"Key": "LINKED_ACCOUNT", "Values": ["111122223333"]}}}.
+            MatchOptions, if given, must be EQUALS. And, Or, and a Not inside another Not are not
+            supported. Applies to get_savings_plans_purchase_recommendation only.
         recommendation_detail_id: Required for get_savings_plan_purchase_recommendation_details. Comes from the RecommendationDetailId field of a recommendation.
         generation_status: SUCCEEDED, PROCESSING, or FAILED. Filters list_savings_plans_purchase_recommendation_generation.
         recommendation_ids: Recommendation IDs to filter to.
@@ -221,7 +224,8 @@ async def get_savings_plans_purchase_recommendation(
             recommendations including the management account and member accounts if the value is
             set to PAYER. If the value is LINKED, recommendations are calculated for individual
             member accounts only.
-        filter_expr: Filter by Account ID with the LINKED_ACCOUNT dimension.
+        filter_expr: Filter by Account ID with the LINKED_ACCOUNT dimension, optionally wrapped in a
+            single Not to exclude those accounts.
         max_items: Total number of recommendation details to return. None fetches every page.
         next_token: The token from a previous response.
 

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

@@ -20,6 +20,7 @@
 lowercase nextToken on the Savings Plans service.
 """
 
+import json
 import pytest
 from awslabs.billing_cost_management_mcp_server.tools.sp_recommendation_tools import (
     get_savings_plan_purchase_recommendation_details,
@@ -709,6 +710,21 @@ async def test_client_creation_failure_is_reported(self, mock_create_client, moc
         assert result['status'] == 'error'
 
 
+@pytest.mark.asyncio
+async def test_filter_doc_states_not_is_supported():
+    """The filter arg doc says Not is accepted around the LINKED_ACCOUNT dimension, with an example."""
+    tool = await sp_recommendation_server.get_tool('sp-recommendation')
+    assert tool is not None
+    filter_doc = ' '.join(tool.parameters['properties']['filter'].get('description', '').split())
+    assert 'optionally wrapped in a single Not to exclude those accounts' in filter_doc
+    example = json.JSONDecoder().raw_decode(filter_doc, filter_doc.index('{"Not"'))[0]
+    assert example == {
+        'Not': {'Dimensions': {'Key': 'LINKED_ACCOUNT', 'Values': ['111122223333']}}
+    }
+    assert 'MatchOptions, if given, must be EQUALS' in filter_doc
+    assert 'And, Or, and a Not inside another Not are not supported' in filter_doc
+
+
 def test_sp_recommendation_server_initialization():
     """The server is named and carries instructions."""
     assert sp_recommendation_server.name == 'sp-recommendation-tools'