fix(billing-cost-management-mcp-server): document COA account scope and criteria, fold restartNeeded criteria (#4904)

* fix(billing-cost-management-mcp-server): document COA account scope and criteria, fold restartNeeded criteria

compute-optimizer-automation:
- Lowercase the values of restartNeeded rule criteria in the preview
  operations. AWS compares restartNeeded against the strings "true" and
  "false", so StringEquals "True" silently matched nothing.
- Describe the criteria shape, its fields and operator types, the
  restartNeeded case rule, and that an OrganizationRule needs
  organization_scope.
- State that from a management account or delegated administrator the
  recommended-action and event list and summary operations include
  associated member accounts, and that summary rows carry no account ID.

* docs(billing-cost-management-mcp-server): drop redundant COA criteria sentences

Remove the operator-type, StringEquals case and restartNeeded lowercase
sentences from the criteria paragraph, and the restartNeeded note from
the criteria arg doc. The field list already pairs String* and Numeric*
operators with their fields, and the tool lowercases restartNeeded
values itself.

Author: finklen-amazon

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

@@ -1048,10 +1048,30 @@ def _rule_preview_request(
         request_params['organizationScope'] = parsed_scope
     parsed_criteria = parse_json(criteria, 'criteria')
     if parsed_criteria:
-        request_params['criteria'] = parsed_criteria
+        request_params['criteria'] = _fold_restart_needed_values(parsed_criteria)
     return request_params
 
 
+def _fold_restart_needed_values(criteria: Any) -> Any:
+    """Lowercase the string values of the restartNeeded criteria conditions.
+
+    AWS compares restartNeeded against the strings "true" and "false", so a StringEquals
+    "True" silently matches nothing. Any shape other than a list of condition objects
+    with a values list is returned unchanged for AWS to validate.
+    """
+    if not isinstance(criteria, dict) or not isinstance(criteria.get('restartNeeded'), list):
+        return criteria
+    conditions = []
+    for condition in criteria['restartNeeded']:
+        if isinstance(condition, dict) and isinstance(condition.get('values'), list):
+            condition = {
+                **condition,
+                'values': [v.lower() if isinstance(v, str) else v for v in condition['values']],
+            }
+        conditions.append(condition)
+    return {**criteria, 'restartNeeded': conditions}
+
+
 async def _collect_automation_rule_preview(
     ctx: Context,
     client: Any,

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

@@ -453,6 +453,13 @@ def _multi_region_guidance(
 list_accounts, list_automation_rules, list_tags_for_resource) accept at most one region —
 rules are global resources, so fanning them out would repeat identical data.
 
+**Account scope:** Called from an organization's management account or a delegated
+administrator, list_recommended_actions, list_recommended_action_summaries,
+list_automation_events and list_automation_event_summaries also return data for the
+associated member accounts (see list_accounts), not just the calling account. Actions and
+events have an account_id; summary rows do not, so their counts and savings can cover several
+accounts. To report on one account, filter on AccountId.
+
 Supported operations (pass via the `operation` parameter):
 
 1. get_enrollment_configuration: Current Automation enrollment status for the account.
@@ -513,6 +520,14 @@ def _multi_region_guidance(
   ResourceTagsKey and ResourceTagsValue each search keys and values, so a key filter also
   matches tag values and the reverse. EBS volume types are lowercased for you.
 
+Rule criteria (`criteria`, preview operations) is a JSON object string of the form
+{"<field>": [{"comparison": "<operator>", "values": [...]}]}. Text fields: `region`,
+`resourceArn`, `ebsVolumeType`, `restartNeeded`; they take String* operators (StringEquals,
+StringLike, StringEqualsIgnoreCase, ...). Number fields: `ebsVolumeSizeInGib`,
+`lookBackPeriodInDays`, `estimatedMonthlySavings`; they take Numeric* operators
+(NumericEquals, NumericGreaterThan, ...). `resourceTag` also takes a "key" and String*
+operators. An OrganizationRule needs organization_scope; the tool rejects one without it.
+
 PAGINATION (list_* operations only; the get_* operations and list_tags_for_resource take
 neither max_items nor next_token):
 - max_items is the total number of items returned. If it is omitted, the tool fetches every page for """
@@ -576,7 +591,10 @@ async def compute_optimizer_automation(
         rule_type: Rule type for the preview operations ('OrganizationRule'/'AccountRule').
         recommended_action_types: JSON string array of action types for the preview operations.
         organization_scope: Optional JSON string {accountIds: [...]} for the preview operations.
-        criteria: Optional JSON string of rule criteria conditions for the preview operations.
+            Required when rule_type is OrganizationRule.
+        criteria: Optional JSON object string of rule criteria for the preview operations:
+            {"<field>": [{"comparison": "<operator>", "values": [...]}]}. See the tool
+            description for the fields and operators.
         max_items: Total number of items to return across all pages (per region when
             regions is set). Omit it to fetch every page. List operations only.
         next_token: The pagination.next_token from a previous response; continue with

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

@@ -104,6 +104,33 @@ async def test_tool_registered_with_name():
     assert tool.name == 'compute-optimizer-automation'
 
 
+async def test_description_documents_account_scope_and_value_formats():
+    """The description states the org scope and the criteria shape and fields."""
+    tool = await compute_optimizer_automation_server.get_tool('compute-optimizer-automation')
+    assert tool is not None
+    description = ' '.join((tool.description or '').split())
+
+    # Management and delegated-admin callers see member accounts' data.
+    assert '**Account scope:**' in description
+    scope = description.split('**Account scope:**')[1].split('Supported operations')[0]
+    assert 'member accounts' in scope
+    assert 'AccountId' in scope
+    # The criteria shape and its fields.
+    assert '{"<field>": [{"comparison": "<operator>", "values": [...]}]}' in description
+    for field in (
+        'region',
+        'resourceArn',
+        'ebsVolumeType',
+        'restartNeeded',
+        'ebsVolumeSizeInGib',
+        'lookBackPeriodInDays',
+        'estimatedMonthlySavings',
+        'resourceTag',
+    ):
+        assert f'`{field}`' in description
+    assert 'OrganizationRule needs organization_scope' in description
+
+
 def test_valid_operations_list():
     """VALID_OPERATIONS covers exactly the 13 supported read operations."""
     assert len(VALID_OPERATIONS) == 13
@@ -743,6 +770,107 @@ async def test_preview_summaries_forward_scope_and_criteria(self, mock_ctx):
             'region': [{'comparison': 'StringEquals', 'values': ['us-east-1']}]
         }
 
+    @pytest.mark.parametrize(
+        'operation', ['list_automation_rule_preview', 'list_automation_rule_preview_summaries']
+    )
+    async def test_restart_needed_values_folded_to_lowercase(self, mock_ctx, operation):
+        """The restartNeeded values are lowercased, since AWS matches only "true"/"false".
+
+        Other criteria fields keep their case.
+        """
+        client = MagicMock()
+        getattr(client, operation).return_value = {}
+        criteria = {
+            'restartNeeded': [
+                {'comparison': 'StringEquals', 'values': ['False', 'TRUE']},
+                {'comparison': 'StringNotLike', 'values': ['T*']},
+            ],
+            'ebsVolumeType': [{'comparison': 'StringEquals', 'values': ['GP2']}],
+        }
+
+        await getattr(ops, operation)(
+            mock_ctx,
+            client,
+            rule_type='AccountRule',
+            recommended_action_types='["UpgradeEbsVolumeType"]',
+            criteria=json.dumps(criteria),
+        )
+
+        _, kwargs = getattr(client, operation).call_args
+        assert kwargs['criteria'] == {
+            'restartNeeded': [
+                {'comparison': 'StringEquals', 'values': ['false', 'true']},
+                {'comparison': 'StringNotLike', 'values': ['t*']},
+            ],
+            'ebsVolumeType': [{'comparison': 'StringEquals', 'values': ['GP2']}],
+        }
+
+    async def test_restart_needed_folded_on_multi_region_tool_call(self, mock_ctx):
+        """Through the tool with regions, every region receives the lowercased criteria."""
+        criteria = '{"restartNeeded": [{"comparison": "StringEquals", "values": ["True"]}]}'
+        clients = {}
+
+        def make_client(region=None):
+            client = MagicMock()
+            client.list_automation_rule_preview.return_value = {'previewResults': []}
+            clients[region] = client
+            return client
+
+        with patch(
+            f'{_TOOLS_MODULE}.create_compute_optimizer_automation_client', side_effect=make_client
+        ):
+            result = await automation_fn(
+                mock_ctx,
+                operation='list_automation_rule_preview',
+                regions=['us-east-1', 'eu-west-1'],
+                rule_type='AccountRule',
+                recommended_action_types='["UpgradeEbsVolumeType"]',
+                criteria=criteria,
+            )
+
+        assert result['status'] == STATUS_SUCCESS
+        assert set(clients) == {'us-east-1', 'eu-west-1'}
+        for client in clients.values():
+            _, kwargs = client.list_automation_rule_preview.call_args
+            assert kwargs['criteria'] == {
+                'restartNeeded': [{'comparison': 'StringEquals', 'values': ['true']}]
+            }
+
+    @pytest.mark.parametrize(
+        'criteria, expected',
+        [
+            ({'restartNeeded': 'True'}, {'restartNeeded': 'True'}),
+            ({'restartNeeded': ['True']}, {'restartNeeded': ['True']}),
+            (
+                {'restartNeeded': [{'comparison': 'StringEquals', 'values': 'True'}]},
+                {'restartNeeded': [{'comparison': 'StringEquals', 'values': 'True'}]},
+            ),
+            (
+                {'restartNeeded': [{'comparison': 'StringEquals', 'values': [True, 'True']}]},
+                {'restartNeeded': [{'comparison': 'StringEquals', 'values': [True, 'true']}]},
+            ),
+            (['restartNeeded'], ['restartNeeded']),
+        ],
+    )
+    async def test_restart_needed_fold_leaves_other_shapes(self, mock_ctx, criteria, expected):
+        """Only string values in a well-formed condition are lowercased.
+
+        Any other shape reaches AWS as given, so AWS still reports its own error.
+        """
+        client = MagicMock()
+        client.list_automation_rule_preview.return_value = {}
+
+        await ops.list_automation_rule_preview(
+            mock_ctx,
+            client,
+            rule_type='AccountRule',
+            recommended_action_types='["UpgradeEbsVolumeType"]',
+            criteria=json.dumps(criteria),
+        )
+
+        _, kwargs = client.list_automation_rule_preview.call_args
+        assert kwargs['criteria'] == expected
+
 
 @pytest.mark.asyncio
 class TestEventSummariesAndSteps: