Skip to content

[WAF tool] Add wellarchitectedframework_usageguide_get#2051

Open
sriramkakara wants to merge 5 commits intomainfrom
users/skakara/waf-usage-guide
Open

[WAF tool] Add wellarchitectedframework_usageguide_get#2051
sriramkakara wants to merge 5 commits intomainfrom
users/skakara/waf-usage-guide

Conversation

@sriramkakara
Copy link
Member

@sriramkakara sriramkakara commented Mar 15, 2026 •
edited
Loading

What does this PR do?

Add a new wellarchitectedframework_usageguide_get command to WAF tool.
This command returns a usage guide on how to apply WAF.

image image image

GitHub issue number?

Issue 1927

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
    • Updated servers/Azure.Mcp.Server/CHANGELOG.md and/or servers/Fabric.Mcp.Server/CHANGELOG.md for product changes (features, bug fixes, UI/UX, updated dependencies)
  • 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 and/or servers/Fabric.Mcp.Server/README.md documentation
    • Validate README.md changes using script at eng/scripts/Process-PackageReadMe.ps1. See Package README
    • Updated command list in /servers/Azure.Mcp.Server/docs/azmcp-commands.md and/or /docs/fabric-commands.md
    • Run .\eng\scripts\Update-AzCommandsMetadata.ps1 to update tool metadata in azmcp-commands.md (required for CI)
    • For new or modified tool descriptions, ran ToolDescriptionEvaluator and obtained a score of 0.4 or more and a top 3 ranking for all related test prompts
    • For tools with new names, including new tools or renamed tools, update consolidated-tools.json
    • For renamed tools, follow the Tool Rename Checklist and tag the PR with the breaking-change label
    • For new tools associated with Azure services or publicly available tools/APIs/products, add URL to documentation in the PR description
  • Extra steps for Azure MCP Server tool changes:
    • Updated test prompts in /servers/Azure.Mcp.Server/docs/e2eTestPrompts.md
    • 👉 For Community (non-Microsoft team member) PRs:
      • Security review: Reviewed code for security vulnerabilities, malicious code, or suspicious activities before running tests (crypto mining, spam, data exfiltration, etc.)
      • Manual tests run: added comment /azp run mcp - pullrequest - live to run Live Test Pipeline

Copilot AI review requested due to automatic review settings March 15, 2026 23:35
@sriramkakara sriramkakara requested review from a team and arunrab as code owners March 15, 2026 23:35
@sriramkakara
Copy link
Member Author

sriramkakara commented Mar 15, 2026

/azp run mcp - pullrequest - live

@azure-pipelines
Copy link

azure-pipelines bot commented Mar 15, 2026

Azure Pipelines successfully started running 1 pipeline(s).

Copilot AI reviewed Mar 15, 2026
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new Azure Well-Architected Framework (WAF) “usage guide” tool command that returns an embedded markdown guide describing how AI agents should apply WAF systematically.

Changes:

  • Introduces wellarchitectedframework usageguide get command and wires it into the WAF tool area registration/DI.
  • Adds an embedded markdown usage guide resource and a service to load/cache it.
  • Adds unit tests plus updates to Azure MCP Server command docs and e2e test prompts.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/Commands/UsageGuide/UsageGuideGetCommand.cs New command implementation that returns the usage guide text.
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/Options/UsageGuide/UsageGuideGetOptions.cs Options type for the new no-parameter command.
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/Services/UsageGuide/IUsageGuideService.cs Service contract for retrieving the usage guide content.
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/Services/UsageGuide/UsageGuideService.cs Embedded-resource loader with static caching for guide content.
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/Resources/UsageGuide/usage-guide.md New embedded markdown usage guide content.
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/WellArchitectedFrameworkSetup.cs Registers the new service/command and adds the usageguide subgroup.
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/Azure.Mcp.Tools.WellArchitectedFramework.csproj Embeds *.md resources so the guide ships in the assembly.
tools/Azure.Mcp.Tools.WellArchitectedFramework/tests/.../Commands/UsageGuide/UsageGuideGetCommandTests.cs Unit tests for the new command behavior and error handling.
tools/Azure.Mcp.Tools.WellArchitectedFramework/tests/.../Services/UsageGuide/UsageGuideServiceTests.cs Unit tests for loading/caching/thread-safety of the guide service.
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/Resources/ServiceGuides/service-guides-generation-prompt.md Minor prompt/comment formatting cleanup.
servers/Azure.Mcp.Server/docs/e2eTestPrompts.md Adds prompts for end-to-end validation of the new tool.
servers/Azure.Mcp.Server/docs/azmcp-commands.md Documents the new CLI command entry for usageguide get.

@KarishmaGhiya
Copy link
Member

KarishmaGhiya commented Mar 17, 2026 •
edited
Loading

@sriramkakara There are few steps remaining from the above checklist:

  1. Please run the tool description evaluator and post the results here.
  2. Update consolidated-tools.json
  3. Run live tests if applicable

@sriramkakara
Copy link
Member Author

sriramkakara commented Mar 18, 2026

@sriramkakara There are few steps remaining from the above checklist:

  1. Please run the tool description evaluator and post the results here.
  2. Update consolidated-tools.json
  3. Run live tests if applicable
  1. Waiting for api key
  2. It's already updated
  3. No, we don't have live tests because we are not calling any service.

srnagar
srnagar reviewed Mar 18, 2026
View reviewed changes
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/Commands/UsageGuide/UsageGuideGetCommand.cs
Comment on lines +27 to +30
"Get the Azure Well-Architected Framework usage guide for AI agents. " +
"This guide provides systematic instructions on how to apply the framework when architecting new Azure workloads, " +
"covering the five pillars (reliability, security, cost optimization, operational excellence, and performance efficiency) " +
"and their application through design principles, design strategies, and configuration recommendations.";
Copy link
Member

@srnagar srnagar Mar 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use multiline string $"""

srnagar
srnagar reviewed Mar 18, 2026
View reviewed changes
tools/Azure.Mcp.Tools.WellArchitectedFramework/src/Services/UsageGuide/UsageGuideService.cs
// at the same time when the cache is not yet initialized.
// Thread A: null check → acquire lock → null check again → initialize → release lock
// Thread B: null check → wait for lock (while Thread A is working) → acquire lock → null check again → see it's initialized by Thread A → return
private static void EnsureUsageGuideLoaded()
Copy link
Member

@srnagar srnagar Mar 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider using Lazy<string> to load the resource

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@KarishmaGhiya KarishmaGhiya KarishmaGhiya left review comments

@alzimmermsft alzimmermsft alzimmermsft left review comments

@srnagar srnagar srnagar left review comments

Copilot code review Copilot Copilot left review comments

@arunrab arunrab Awaiting requested review from arunrab arunrab is a code owner

@hallipr hallipr Awaiting requested review from hallipr hallipr is a code owner automatically assigned from microsoft/azure-mcp

@jongio jongio Awaiting requested review from jongio jongio is a code owner automatically assigned from microsoft/azure-mcp

@wbreza wbreza Awaiting requested review from wbreza wbreza is a code owner automatically assigned from microsoft/azure-mcp

@conniey conniey Awaiting requested review from conniey conniey is a code owner automatically assigned from microsoft/azure-mcp

@tmeschter tmeschter Awaiting requested review from tmeschter tmeschter is a code owner automatically assigned from microsoft/azure-mcp

@sandeep-sen sandeep-sen Awaiting requested review from sandeep-sen sandeep-sen is a code owner automatically assigned from microsoft/azure-mcp

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

tools-WellArchitectedFramework

Projects

Azure MCP Server
Status: Untriaged

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@sriramkakara @KarishmaGhiya @alzimmermsft @srnagar