Add Advisor recommendation update tool

[Ravi Gupta (ravigupta99)]

What does this PR do?

Adds advisor recommendation update, a new Azure Advisor MCP tool that updates the customer-provided state of a recommendation through the Advisor Recommendations Update REST API.

The tool:

• Accepts subscription (ID or name), the recommendation stable ID as recommendation-id, and the target state.
• Supports New, Postponed, Dismissed, and Completed.
• Requires a future ISO 8601 date-time for Postponed, preserving the supplied timezone offset with DateTimeOffset.
• Requires an explicit documented dismissal reason for Dismissed; it does not silently invent Other.
• Guides natural-language mapping to dismissal reasons, including RiskIsAcceptable and ExcessiveCostInvestmentRequired.
• Surfaces actionable errors for Security-category, Undefined-state, platform-resolved, not-found, and concurrent-update cases.
• Returns a concise shared recommendation model used by recommendation listing and updating.
• Uses authenticated, sovereign-cloud-aware ARM requests through the Azure Core pipeline, with retries capped at three.
• Uses AOT-safe source-generated System.Text.Json serialization.

Validation completed:

• 256 Azure Advisor tests passed.
• Azure MCP Server and Advisor projects built with zero warnings and errors.
• Build-Local.ps1 -VerifyNpx passed.
• Native/AOT build passed.
• Repository spelling validation passed.
• Command metadata generation, changelog validation, and README package validation passed.
• ToolDescriptionEvaluator ranked the tool first for all four related prompts, with scores from 0.4472 to 0.5330.

Advisor currently has HasLiveTests=false and no deterministic infrastructure for provisioning an actionable recommendation, so this PR adds comprehensive command, ARM request, retry, response-conversion, validation, and error-handling tests rather than a recorded live test.

GitHub issue number?

#3381

Pre-merge Checklist

• Required for All PRs
  • Read contribution guidelines
  • PR title clearly describes the change
  • Commit history is clean with descriptive messages (cleanup guide)
  • Added comprehensive tests for new/modified functionality
  • Created a changelog entry if the change falls among the following: new feature, bug fix, UI/UX update, breaking change, or updated dependencies. Follow the changelog entry guide
• For MCP tool changes:
  • One tool per PR: This PR adds or modifies only one MCP tool for faster review cycles
  • Updated servers/Azure.Mcp.Server/README.md documentation
  • Validated README.md changes using Process-PackageReadMe.ps1
  • Ran ToolDescriptionEvaluator and obtained a score of 0.4 or more and a top 3 ranking for all related test prompts
  • Updated consolidated-tools.json
  • Added the public Azure Advisor API documentation URL
• Extra steps for Azure MCP Server tool changes:
  • Updated servers/Azure.Mcp.Server/docs/azmcp-commands.md
  • Ran Update-AzCommandsMetadata.ps1
  • Updated servers/Azure.Mcp.Server/docs/e2eTestPrompts.md

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.

[Copilot]

Pull request overview

Adds a new Azure Advisor tool (advisor recommendation patch) to update the customer-provided lifecycle state of a recommendation via the Advisor Recommendations Update ARM API, and wires it into the Azure MCP Server tool catalog/docs with supporting serialization and test coverage.

Changes:

• Added advisor recommendation patch command + options, service implementation, and AOT-safe JSON request/response handling.
• Expanded the shared Advisor Recommendation model and conversion logic to include lifecycle/state fields used by the patch tool.
• Updated Azure MCP Server tool registry/docs/prompts and added unit tests covering patch request construction, retries, and error handling.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/Azure.Mcp.Tools.Advisor/tests/Azure.Mcp.Tools.Advisor.Tests/Services/AdvisorServiceConversionTests.cs	Adds conversion coverage for new lifecycle/shared response fields.
tools/Azure.Mcp.Tools.Advisor/tests/Azure.Mcp.Tools.Advisor.Tests/Services/AdvisorRecommendationPatchServiceTests.cs	Adds service-level tests for PATCH request shaping, auth/cloud routing, retry, and error handling.
tools/Azure.Mcp.Tools.Advisor/tests/Azure.Mcp.Tools.Advisor.Tests/Recommendation/RecommendationPatchCommandTests.cs	Adds command tests for validation, forwarding args, and response shaping.
tools/Azure.Mcp.Tools.Advisor/src/Services/Models/RecommendationStatePatchRequest.cs	Adds request envelope model for the PATCH call.
tools/Azure.Mcp.Tools.Advisor/src/Services/Models/RecommendationStatePatchProperties.cs	Adds PATCH request properties model (status + optional fields).
tools/Azure.Mcp.Tools.Advisor/src/Services/Models/RecommendationProperties.cs	Extends deserialization model to include lifecycle/state and additional recommendation fields.
tools/Azure.Mcp.Tools.Advisor/src/Services/Models/RecommendationDescription.cs	Adds Solution field used in recommendation conversion/output.
tools/Azure.Mcp.Tools.Advisor/src/Services/IAdvisorService.cs	Introduces the PatchRecommendationAsync service contract.
tools/Azure.Mcp.Tools.Advisor/src/Services/AdvisorService.cs	Implements PATCH call + retry logic and enriches recommendation conversion output.
tools/Azure.Mcp.Tools.Advisor/src/Options/Recommendation/RecommendationPatchOptions.cs	Adds CLI options for patching state, postpone date, and dismissal reason.
tools/Azure.Mcp.Tools.Advisor/src/Models/RecommendationStatus.cs	Adds enum for supported recommendation lifecycle states.
tools/Azure.Mcp.Tools.Advisor/src/Models/RecommendationDismissReason.cs	Adds enum for supported dismissal reasons.
tools/Azure.Mcp.Tools.Advisor/src/Models/Recommendation.cs	Expands shared response model to include lifecycle/shared response fields.
tools/Azure.Mcp.Tools.Advisor/src/Commands/Recommendation/RecommendationPatchCommand.cs	Adds the new MCP command, validation, execution, and error mapping.
tools/Azure.Mcp.Tools.Advisor/src/Commands/AdvisorJsonContext.cs	Registers new request/response types for source-generated JSON (AOT safe).
tools/Azure.Mcp.Tools.Advisor/src/AdvisorSetup.cs	Registers the new command in DI and command group wiring.
servers/Azure.Mcp.Server/src/Resources/consolidated-tools.json	Adds the new consolidated tool entry mapping to advisor_recommendation_patch.
servers/Azure.Mcp.Server/README.md	Adds example prompts and updates Advisor capability summary.
servers/Azure.Mcp.Server/docs/e2eTestPrompts.md	Adds e2e prompt rows for the new tool.
servers/Azure.Mcp.Server/docs/azmcp-commands.md	Documents the new azmcp advisor recommendation patch command syntax and semantics.
servers/Azure.Mcp.Server/changelog-entries/guptaravi-advisor-recommendation-patch.yml	Adds a changelog entry for the new tool.

---

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

[Ravi Gupta (ravigupta99)]

The required Vally evaluations / eval-job check did not evaluate the earlier commits: all 34/34 Advisor trials errored with Session was not created with authentication info or custom provider. The workflow received no COPILOT_GITHUB_TOKEN because this PR originates from a fork, and the workflow is now disabled, so that hosted run cannot be retried.

Resolved with local Vally evidence: after installing Vally 0.13.0 and authenticating the Copilot CLI, I rebuilt the merged branch and ran four concrete Advisor recommendation-update trials (dismiss, complete, postpone, and reactivate) against the local Azure MCP binary. All 4/4 trials selected advisor_recommendation_update and passed the tool-calls grader. The operations stopped at the expected consent boundary because Vally cannot answer destructive-operation elicitation; tool selection itself was successful. Local ToolDescriptionEvaluator validation also ranks advisor_recommendation_update first for all four prompts with scores 0.4472–0.5330.

[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.

[Vinay Gera (g2vinay)]

A couple of non-blocking notes on the new Advisor recommendation update tool: one on recommendation-id discoverability from list, and one on dismiss-reason handling for non-Dismissed statuses. Overall the change looks solid.