fix(billing-cost-management-mcp-server): name INSTANCE_TYPE_FAMILY for SP coverage, document SP filters, add sort_by (#4901)

* fix(billing-cost-management-mcp-server): name INSTANCE_TYPE_FAMILY for SP coverage, document SP filters, add sort_by

The sp-performance description told callers to use INSTANCE_FAMILY for
GetSavingsPlansCoverage group_by and filter. The service rejects that key;
it accepts INSTANCE_TYPE_FAMILY, the same key the utilization operations use.
Name INSTANCE_TYPE_FAMILY everywhere and drop the note contrasting the two.

Also document what the description left out:
- get_savings_plans_utilization filter dimensions, and that only Dimensions,
  And and Not are allowed (Or, Tags and CostCategories are rejected). The
  filter text no longer says "And/Or", since Or is not accepted.
- SAVINGS_PLANS_TYPE is not a coverage dimension.
- The exact PAYMENT_OPTION and SAVINGS_PLANS_TYPE value spellings; any other
  spelling returns a DataUnavailableException with no service message rather
  than a ValidationException, so check the spelling before moving the window.

Add an optional sort_by (JSON string, passed through as SortBy) for coverage
and utilization details, with each operation's sort keys. The API sorts
before paging, so sort_by plus max_items gives a top N. Utilization ignores
it: sorting there reorders the time periods out of date order.

* fix(billing-cost-management-mcp-server): list all SP utilization details filters; note coverage sort needs group_by

get_savings_plans_utilization_details also filters on SAVINGS_PLANS_TYPE and
on the plan end-date bounds AGREEMENT_END_DATE_TIME_AFTER and
AGREEMENT_END_DATE_TIME_BEFORE (YYYY-MM-DD). The description listed only five
dimensions and scoped SAVINGS_PLANS_TYPE to utilization, steering callers
away from a filter details accepts.

Sorting coverage by InstanceFamily, Region or Service needs that dimension
in group_by; otherwise the API returns "SortKey=[Region] should be in
groupBy list to provide sorting". Say so next to the coverage sort keys.

* docs(billing-cost-management-mcp-server): say sp-performance sorts before max_items

State the order of operations for sort_by and max_items: the API sorts
every matching item by the key first and then pages, and max_items=N keeps
the first N of that order. sort_by plus max_items=N is therefore the top N
by the key, not N arbitrary items sorted afterwards. Checked live: with
group_by INSTANCE_TYPE_FAMILY and sort_by OnDemandCost DESCENDING,
max_items=3 returned exactly the first 3 groups of the full sorted list,
while the same request without sort_by returned a different 3.

Author: finklen-amazon

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

@@ -51,11 +51,12 @@
 3. get_savings_plans_utilization_details: Shows detailed per-Savings Plan utilization
 
 COVERAGE grouping and filtering (get_savings_plans_coverage):
-- group_by accepts ONLY INSTANCE_FAMILY, REGION, or SERVICE. LINKED_ACCOUNT is
+- group_by accepts ONLY INSTANCE_TYPE_FAMILY, REGION, or SERVICE. LINKED_ACCOUNT is
   NOT a valid group_by attribute — grouping by it returns a ValidationException.
-- filter accepts LINKED_ACCOUNT, REGION, SERVICE, INSTANCE_FAMILY. To see coverage
+- filter accepts LINKED_ACCOUNT, REGION, SERVICE, INSTANCE_TYPE_FAMILY. To see coverage
   per member account, FILTER by one LINKED_ACCOUNT and call once per account; do
-  not try to group_by LINKED_ACCOUNT.
+  not try to group_by LINKED_ACCOUNT. SAVINGS_PLANS_TYPE is not a coverage dimension
+  (ValidationException).
 - Each group_by entry is a GroupDefinition with Type and Key, e.g.
   `[{"Type": "DIMENSION", "Key": "REGION"}]`. There is no "Value" field in a
   group_by entry — a `{Key, Value}` shape is rejected (seen as a boto
@@ -77,14 +78,46 @@
   utilization or coverage) and do NOT resend the identical request. Correct an unknown
   filter value; query an earlier window only if the question allows it.
 
+UTILIZATION filters (get_savings_plans_utilization):
+- filter accepts LINKED_ACCOUNT, SAVINGS_PLAN_ARN, SAVINGS_PLANS_TYPE, REGION,
+  PAYMENT_OPTION, INSTANCE_TYPE_FAMILY. Only Dimensions, And and Not are allowed; an Or,
+  Tags or CostCategories expression returns a ValidationException.
+
 UTILIZATION DETAILS filters (get_savings_plans_utilization_details):
-- filter accepts LINKED_ACCOUNT, SAVINGS_PLAN_ARN, REGION, PAYMENT_OPTION,
-  INSTANCE_TYPE_FAMILY (note INSTANCE_TYPE_FAMILY here, INSTANCE_FAMILY for coverage).
-- The filter is a Cost Explorer Expression. And/Or each require at least TWO
+- filter accepts LINKED_ACCOUNT, SAVINGS_PLAN_ARN, SAVINGS_PLANS_TYPE, REGION,
+  PAYMENT_OPTION, INSTANCE_TYPE_FAMILY, AGREEMENT_END_DATE_TIME_AFTER and
+  AGREEMENT_END_DATE_TIME_BEFORE (one YYYY-MM-DD value each, compared with each plan's
+  end date).
+- The filter is a Cost Explorer Expression. And requires at least TWO
   operands ("And expression must have at least 2 operands"). For a single
   condition, pass the leaf object directly — e.g.
   `{"Dimensions": {"Key": "REGION", "Values": ["us-east-1"]}}` — not wrapped in
-  a one-element `And`/`Or`.
+  a one-element `And`.
+
+FILTER VALUES (exact, case-sensitive spellings):
+- PAYMENT_OPTION: "No Upfront", "Partial Upfront", "All Upfront".
+- SAVINGS_PLANS_TYPE (get_savings_plans_utilization and
+  get_savings_plans_utilization_details; not accepted by coverage): "ComputeSavingsPlans",
+  "EC2InstanceSavingsPlans", "SageMakerSavingsPlans", "DatabaseSavingsPlans".
+- Any other spelling (NO_UPFRONT, Compute, COMPUTE_SP) matches nothing and returns a
+  DataUnavailableException, which the service sends without a message, not a
+  ValidationException. On that error with a filter set, check these spellings before
+  changing the window.
+
+SORTING (sort_by; get_savings_plans_coverage and get_savings_plans_utilization_details):
+- A JSON string `{"Key": "...", "SortOrder": "ASCENDING" or "DESCENDING"}`.
+- Order of operations: the API sorts every matching item by the key first, then pages;
+  max_items=N keeps the first N of that sorted order. So sort_by + max_items=N returns the
+  top N items by the key across everything that matches, not N arbitrary items sorted
+  afterwards (see PAGINATION for what an item is).
+- Coverage keys: CoveragePercentage, SpendCoveredBySavingsPlan (singular, unlike the
+  metric), OnDemandCost, TotalCost, InstanceFamily, Region, Service. Sort keys are not
+  dimension names: sort by InstanceFamily, group by INSTANCE_TYPE_FAMILY. Sorting coverage
+  by InstanceFamily, Region or Service needs that dimension in group_by
+  (INSTANCE_TYPE_FAMILY, REGION or SERVICE); otherwise the API returns a ValidationException.
+- Utilization details keys: UtilizationPercentage, TotalCommitment, UsedCommitment,
+  UnusedCommitment, NetSavings, AmortizedRecurringCommitment, AmortizedUpfrontCommitment.
+- get_savings_plans_utilization ignores sort_by and returns its periods in date order.
 
 RESPONSE PERIODS (all three operations):
 - `requested_time_period` echoes the start_date/end_date that were sent.
@@ -99,7 +132,7 @@
 IMPORTANT: For get_savings_plans_coverage, `granularity` and `group_by` are mutually
 exclusive. If `group_by` is provided, `granularity` is ignored (the Cost Explorer
 GetSavingsPlansCoverage API does not allow both). Valid `group_by` dimensions for
-coverage are SERVICE, REGION, or INSTANCE_FAMILY.
+coverage are SERVICE, REGION, or INSTANCE_TYPE_FAMILY.
 
 PAGINATION (get_savings_plans_coverage, where an item is one period x group entry, and
 get_savings_plans_utilization_details, where an item is one Savings Plan;
@@ -125,6 +158,7 @@ async def sp_performance(
     filter: Optional[str] = None,
     max_items: Optional[int] = None,
     next_token: Optional[str] = None,
+    sort_by: Optional[str] = None,
 ) -> Dict[str, Any]:
     """Tool that retrieves AWS Savings Plans coverage and utilization data.
 
@@ -135,12 +169,17 @@ async def sp_performance(
         end_date: End date in YYYY-MM-DD format (exclusive). Defaults to today if not provided. Savings Plans data for the last 2-3 days (counting today) is not processed yet: a start_date in those days returns a DataUnavailableException, and a window reaching into them leaves them out.
         granularity: Time granularity of the data (DAILY or MONTHLY). Defaults to DAILY. For coverage, ignored when group_by is provided (granularity and group_by are mutually exclusive).
         metrics: List of metrics to retrieve as a JSON string. For coverage, only 'SpendCoveredBySavingsPlans' is valid.
-        group_by: Optional grouping of results as a JSON string. For coverage, supports SERVICE, REGION, or INSTANCE_FAMILY (NOT LINKED_ACCOUNT). Each entry is {"Type": ..., "Key": ...}; there is no "Value" field.
-        filter: Optional filter to apply to the results as a JSON string. Coverage filter dimensions: LINKED_ACCOUNT, REGION, SERVICE, INSTANCE_FAMILY. And/Or need >=2 operands; for one condition pass the leaf object directly.
+        group_by: Optional grouping of results as a JSON string. For coverage, supports SERVICE, REGION, or INSTANCE_TYPE_FAMILY (NOT LINKED_ACCOUNT). Each entry is {"Type": ..., "Key": ...}; there is no "Value" field.
+        filter: Optional filter to apply to the results as a JSON string. Coverage filter dimensions: LINKED_ACCOUNT, REGION, SERVICE, INSTANCE_TYPE_FAMILY. And needs >=2 operands; for one condition pass the leaf object directly. Values are case-sensitive; see FILTER VALUES in the tool description.
         max_items: Total number of items to return across all pages. Omit it to fetch every
-            page. Coverage and utilization details only.
+            page. Coverage and utilization details only. With sort_by, these are the first N
+            items in the requested SortOrder (the top N), not N items sorted afterwards.
         next_token: The pagination.next_token from a previous response; continue with otherwise
             identical parameters. Coverage and utilization details only.
+        sort_by: Optional sort as a JSON string, e.g. {"Key": "CoveragePercentage", "SortOrder": "ASCENDING"}.
+            Applied before max_items, so sort_by + max_items=N returns the top N.
+            Coverage and utilization details only (ignored by get_savings_plans_utilization);
+            the valid keys differ per operation (see SORTING).
 
     Returns:
         Dict containing the savings plans coverage/utilization information
@@ -163,14 +202,15 @@ async def sp_performance(
                 filter,
                 max_items,
                 next_token,
+                sort_by,
             )
         elif operation == 'get_savings_plans_utilization':
             return await get_savings_plans_utilization(
                 ctx, ce_client, start_date, end_date, granularity, filter
             )
         elif operation == 'get_savings_plans_utilization_details':
             return await get_savings_plans_utilization_details(
-                ctx, ce_client, start_date, end_date, filter, max_items, next_token
+                ctx, ce_client, start_date, end_date, filter, max_items, next_token, sort_by
             )
         else:
             return format_response(
@@ -205,6 +245,7 @@ async def get_savings_plans_coverage(
     filter_expr: Optional[str],
     max_items: Optional[int] = None,
     next_token: Optional[str] = None,
+    sort_by: Optional[str] = None,
 ) -> Dict[str, Any]:
     """Retrieves Savings Plans coverage data.
 
@@ -219,6 +260,7 @@ async def get_savings_plans_coverage(
         filter_expr: Filter expression as JSON string
         max_items: Total number of coverage entries to return. None fetches every page.
         next_token: The token from a previous response.
+        sort_by: Sort definition as JSON string
 
     Returns:
         Dict containing coverage data
@@ -256,6 +298,9 @@ async def get_savings_plans_coverage(
         if filter_expr:
             request_params['Filter'] = parse_json(filter_expr, 'filter')
 
+        if sort_by:
+            request_params['SortBy'] = parse_json(sort_by, 'sort_by')
+
         all_coverages, _, pagination = await paginate_aws_items(
             ctx,
             'GetSavingsPlansCoverage',
@@ -374,6 +419,7 @@ async def get_savings_plans_utilization_details(
     filter_expr: Optional[str],
     max_items: Optional[int] = None,
     next_token: Optional[str] = None,
+    sort_by: Optional[str] = None,
 ) -> Dict[str, Any]:
     """Retrieves detailed Savings Plans utilization data.
 
@@ -385,6 +431,7 @@ async def get_savings_plans_utilization_details(
         filter_expr: Filter expression as JSON string
         max_items: Total number of Savings Plans to return. None fetches every page.
         next_token: The token from a previous response.
+        sort_by: Sort definition as JSON string
 
     Returns:
         Dict containing detailed utilization data
@@ -408,6 +455,9 @@ async def get_savings_plans_utilization_details(
         if filter_expr:
             request_params['Filter'] = parse_json(filter_expr, 'filter')
 
+        if sort_by:
+            request_params['SortBy'] = parse_json(sort_by, 'sort_by')
+
         all_details, pages, pagination = await paginate_aws_items(
             ctx,
             'GetSavingsPlansUtilizationDetails',