Improve Advisor recommendation summaries

[Ravi Gupta (ravigupta99)]

What does this PR do?

Improves advisor_recommendation_summary so aggregate Advisor questions return canonical, complete, and correctly grouped recommendation counts.

This PR:

• adds seven grouping dimensions: recommendation type, category, impact, impacted resource type, lifecycle status, metadata subcategory, and service-retirement date;
• returns every bucket as { key, label, count }, using recommendation type IDs with English metadata labels;
• uses metadata-authoritative category, impact, subcategory, and retirement values with recommendation-instance fallback;
• uses properties.impactedField for resource-type filtering/grouping, with resource-ID extraction only as a grouping fallback;
• preserves active New recommendations by default while status grouping includes all lifecycle states;
• adds recommendation type, subcategory, and retirement-date filters with strict validation;
• validates --top as 1-100 while preserving the full total and a trailing Unknown bucket;
• moves aggregation into a dedicated summary service and shares safe instance-predicate construction with recommendation list;
• restricts recommendation queries to the current engine using strlen(name) == 64 and isempty(properties.serviceGroupId);
• expands evaluator coverage with realistic aggregate prompts.

Breaking change and migration

For --group-by recommendation-type, groups[].key changes from recommendation problem text to the recommendation type ID GUID. groups[].label contains the friendly metadata display name. Callers that used problem-text keys must migrate to the GUID key and use label for presentation.

Retirement-date semantics

Retirement comparisons are one-sided. le:<end-date> includes all active recommendations retiring on or before the end date, including overdue retirements; it is not a bounded next-N window. The tool description and prompts now use explicit exact, on-or-before, and on-or-after semantics.

Recommendation-list hardening

This PR also changes the shared query predicates used by advisor_recommendation_list:

• strlen(name) == 64 excludes legacy non-64-character recommendation IDs to prevent duplicate old-engine and new-engine recommendation instances;
• isempty(properties.serviceGroupId) reserves the future service-group recommendation flavor.

Current live list results are unchanged: every observed record in the supported New, Completed, Dismissed, and Postponed states has a 64-character current-engine ID, all 1,005 legacy records have no supported list status, and no current records have a nonempty serviceGroupId. The legacy names are 36 characters in the current live data.

Dependency

PRs #3303 and #3307 are merged. This branch has been synchronized with the resulting main.

GitHub issue number?

Enhancement to the existing Advisor recommendation summary tool; no new onboarding issue was created.

Validation

• dotnet test tools\Azure.Mcp.Tools.Advisor\tests\Azure.Mcp.Tools.Advisor.Tests\Azure.Mcp.Tools.Advisor.Tests.csproj
  • 354 passed
• dotnet build servers\Azure.Mcp.Server\src\Azure.Mcp.Server.csproj
  • passed with 0 warnings/errors
• dotnet format Microsoft.Mcp.slnx --verify-no-changes --include "tools\Azure.Mcp.Tools.Advisor\**\*.cs"
  • passed
• .\eng\common\spelling\Invoke-Cspell.ps1
  • passed
• .\eng\common\scripts\check-spelling-in-changed-files.ps1 ... -ExitWithError
  • passed; 21 changed files checked with 0 issues
• .\eng\scripts\Process-PackageReadMe.ps1 -Command validate -InputReadMePath .\servers\Azure.Mcp.Server\README.md
  • passed
• .\eng\scripts\Update-AzCommandsMetadata.ps1
  • passed; 383 tools loaded after synchronizing with Add Advisor recommendation update tool #3303
• .\eng\scripts\Compile-Changelog.ps1 -ChangelogPath servers\Azure.Mcp.Server\CHANGELOG.md -DryRun
  • passed
• .\eng\scripts\Build-Local.ps1 -VerifyNpx
  • passed

Tool selection

ToolDescriptionEvaluator passed all 21 advisor_recommendation_summary prompts:

• ranks: 1-3;
• scores: 0.409321-0.617694.

A focused Vally suite against the exact locally built azmcp.exe passed 3/3 reviewed boundaries: scoped recommendation-type ranking, overdue-inclusive retirement summary, and individual retirement records.

Live Azure validation

The exact branch binary was exercised against live Advisor data for all seven groupings and every public filter/validation path.

• exhaustive CLI matrix: 69/69 passed;
• independent ARG comparison matrix: 11/11 passed;
• 1,005 legacy non-64-character recommendation records excluded; the observed legacy names are 36 characters and have no supported list status;
• current serviceGroupId exclusions: 0 (forward-looking filter);
• every observed record in supported list statuses already uses a 64-character stable ID, so the list hardening does not change current returned rows;
• category, impact, recommendation type, resource type, status, subcategory, and retirement-date results matched independent ARG queries;
• metadata-aware results were independently verified through tenant-scoped Resource Graph REST queries with no request-level subscription or management-group scope.

Advisor does not currently have deterministic recorded-test resource infrastructure for generated recommendations or global metadata. This PR follows the established Advisor exception with comprehensive command/query tests, exact local-binary Azure calls, and independent ARG comparisons.

Native AOT

.\eng\scripts\Build-Local.ps1 -IncludeNative completed its wrapper and packaging flow but the inner Azure MCP native publish reported existing Cosmos dependency diagnostics:

• IL2026 and IL3050 in Microsoft.Azure.Documents.JsonSerializable.SetValueCollection<T>;
• MSB3077 from the Native AOT compiler.

The Advisor projects build with no warnings. The native failure is pre-existing and unrelated to this change.

Pre-merge Checklist

• Read contribution guidelines
• One MCP tool modified: this PR intentionally includes a tightly coupled recommendation-list duplicate-prevention and future-flavor safeguard through the shared query builder
• Added comprehensive tests
• Added a changelog entry
• Updated Azure MCP README
• Updated azmcp-commands.md and regenerated metadata
• Updated e2eTestPrompts.md
• Updated consolidated-tool wording
• Added a Breaking Changes entry and migration note for recommendation-type groups[].key
• ToolDescriptionEvaluator score is at least 0.4 and rank is top 3 for every summary prompt
• Ran comprehensive Vally routing validation
• Ran live local-binary and independent ARG validation
• Synchronized with main after dependency Add Advisor recommendation update tool #3303 merged

Invoking Livetests

Copilot submitted PRs are not trustworthy by default. Users with write access to the repo need to validate the contents of this PR before leaving a comment with the text /azp run mcp - pullrequest - live. This will trigger the necessary livetest workflows to complete required validation.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟢 Approval recommended

The changes are comprehensive, internally consistent across command/service/validation/docs, and the updated/added unit tests substantively cover the new query-building and summary-shaping behavior.

Pull request overview

This PR upgrades the advisor_recommendation_summary tool to produce canonical, metadata-backed aggregation results across additional grouping dimensions (including lifecycle status, metadata subcategory, and service-retirement date), while tightening validation and aligning summary/list filtering semantics via shared query-building utilities.

Changes:

• Added a dedicated RecommendationSummaryService that builds current-engine-safe ARG queries and returns { key, label, count } buckets with stable recommendation type IDs and English metadata labels.
• Centralized and hardened KQL predicate construction (including current-engine filtering) via RecommendationQueryBuilder, and expanded/normalized validation for filters and --top.
• Updated command surface + docs/prompts/changelog and expanded tests to cover the new grouping/filtering behavior.

File summaries

File	Description
tools/Azure.Mcp.Tools.Advisor/tests/Azure.Mcp.Tools.Advisor.Tests/Services/RecommendationSummaryServiceTests.cs	Adds coverage for summary query composition, parsing/sorting, truncation handling, and retirement filter validation.
tools/Azure.Mcp.Tools.Advisor/tests/Azure.Mcp.Tools.Advisor.Tests/Services/RecommendationQueryBuilderTests.cs	Adds coverage for shared instance predicate construction and KQL sanitization semantics.
tools/Azure.Mcp.Tools.Advisor/tests/Azure.Mcp.Tools.Advisor.Tests/Services/AdvisorServiceSummarizeQueryTests.cs	Removes legacy summarize-query tests replaced by the new summary service.
tools/Azure.Mcp.Tools.Advisor/tests/Azure.Mcp.Tools.Advisor.Tests/Services/AdvisorServiceFilterBuilderTests.cs	Removes legacy filter-builder tests replaced by RecommendationQueryBuilder.
tools/Azure.Mcp.Tools.Advisor/tests/Azure.Mcp.Tools.Advisor.Tests/Recommendation/RecommendationSummaryCommandTests.cs	Updates command tests for new groupings, validations, normalized filters, payload shape, and top/Unknown behavior.
tools/Azure.Mcp.Tools.Advisor/src/Validation/ServiceRetirementFilterValidator.cs	Extends shared retirement validation to support summary grouping and stricter empty/format checks.
tools/Azure.Mcp.Tools.Advisor/src/Validation/RecommendationFilterValidator.cs	Extracts shared validation/normalization helpers for summary + list.
tools/Azure.Mcp.Tools.Advisor/src/Services/RecommendationSummaryService.cs	Implements metadata-backed summary querying, grouping, and payload parsing.
tools/Azure.Mcp.Tools.Advisor/src/Services/RecommendationQueryBuilder.cs	Introduces shared, injection-resistant KQL predicate construction and current-engine restrictions.
tools/Azure.Mcp.Tools.Advisor/src/Services/IRecommendationSummaryService.cs	Adds a dedicated summary service contract.
tools/Azure.Mcp.Tools.Advisor/src/Services/IAdvisorService.cs	Removes the summary API from the main advisor service contract.
tools/Azure.Mcp.Tools.Advisor/src/Services/AdvisorService.cs	Switches list filtering to the shared predicate builder and removes the legacy summary implementation.
tools/Azure.Mcp.Tools.Advisor/src/Options/Recommendation/RecommendationSummaryOptions.cs	Expands summary options with new filters and clarifies semantics/limits.
tools/Azure.Mcp.Tools.Advisor/src/Options/Recommendation/RecommendationListOptions.cs	Clarifies list --top semantics now that summary has its own cap.
tools/Azure.Mcp.Tools.Advisor/src/Models/RecommendationGroup.cs	Expands group model to include label alongside key and count.
tools/Azure.Mcp.Tools.Advisor/src/Commands/Recommendation/RecommendationSummaryCommand.cs	Updates command DI + validation + normalization + error handling and top/Unknown slicing behavior.
tools/Azure.Mcp.Tools.Advisor/src/AdvisorSetup.cs	Registers the new summary service and updates group description text.
tools/Azure.Mcp.Tools.Advisor/cspell.yaml	Adds leftouter to support KQL test strings.
servers/Azure.Mcp.Server/src/Resources/consolidated-tools.json	Refreshes the public tool description to reflect new summary capabilities and constraints.
servers/Azure.Mcp.Server/README.md	Adds example prompts and updates the Advisor service listing text.
servers/Azure.Mcp.Server/docs/e2eTestPrompts.md	Expands realistic evaluator prompts for the updated summary tool.
servers/Azure.Mcp.Server/docs/azmcp-commands.md	Updates CLI docs for the expanded summary command surface and semantics.
servers/Azure.Mcp.Server/changelog-entries/guptaravi-advisor-recommendation-summary.yml	Adds a schema-shaped changelog entry for the feature + fixes.

Review details

• Files reviewed: 24/24 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.