feat: add azure agent code gen best practice tool

[XiaofuHuang]

What does this PR do?

• Proposed new namespace:
  Azure.Mcp.Tools.AzureAgentBestPractices (AzureAgentBestPractices namespace)
  This namespace provides best practices guidance for building AI applications and agents in Azure.
• Proposed new tool:
  azureagentbestpractices_get
  The associated tool offers actionable recommendations for developers before generating code for any AI apps/agents in Azure. It recommends developing with Azure AI Foundry models, working with the Microsoft Agent Framework, or implementing AI agents within Azure AI Foundry. It is intended to be used when users are coding AI apps/agents in Azure.

Microsoft Agent Framework: https://learn.microsoft.com/en-us/agent-framework/user-guide/agents/agent-types/azure-ai-foundry-agent?pivots=programming-language-csharp

GitHub issue number?

#960

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 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]

Pull Request Overview

This PR adds a new Azure Agent Best Practices toolset that provides comprehensive guidance for building AI agents with Azure AI Foundry and Microsoft Agent Framework. The implementation follows the existing pattern of best practices tools in the codebase (similar to AzureBestPractices and AzureTerraformBestPractices).

Key changes:

• New tool command that returns best practices text from an embedded resource file covering model selection, SDK recommendations, and implementation patterns
• Integration of the new tool into the server's area registration and consolidated tools list
• Comprehensive test coverage for the new command
• Documentation updates including commands reference, E2E test prompts, and CHANGELOG

Reviewed Changes

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

Show a summary per file

File	Description
tools/Azure.Mcp.Tools.AzureAgentBestPractices/src/Commands/AzureAgentBestPracticesGetCommand.cs	Implements the command to retrieve agent best practices from embedded resource
tools/Azure.Mcp.Tools.AzureAgentBestPractices/src/AzureAgentBestPracticesSetup.cs	Registers the command group and configures dependency injection
tools/Azure.Mcp.Tools.AzureAgentBestPractices/src/Resources/agent-best-practices-for-azure.txt	Contains 413 lines of detailed best practices guidance text
tools/Azure.Mcp.Tools.AzureAgentBestPractices/tests/Azure.Mcp.Tools.AzureAgentBestPractices.UnitTests/AzureAgentBestPracticesGetCommandTests.cs	Unit test validating command execution and response content
servers/Azure.Mcp.Server/src/Program.cs	Registers the new area setup in the server
core/Azure.Mcp.Core/src/Areas/Server/Resources/consolidated-tools.json	Adds the tool to the consolidated Azure best practices group
core/Azure.Mcp.Core/src/Areas/Server/Resources/azure-rules.txt	Documents when to invoke the agent best practices tool
servers/Azure.Mcp.Server/docs/*.md	Updates command documentation and E2E test prompts
.github/CODEOWNERS	Adds code ownership for the new tool
AzureMcp.sln	Adds projects to the solution file
eng/tools/ToolDescriptionEvaluator/*.json	Updates tool metadata and test prompts

[joshfree]

I agree we should consolidate best practices tools. We spent a lot of effort condensing the 5-6 previous best practices into 2.

I'd expect us to have test results with the two different namespace designs and take a data driven approach here.

[fanyang-mono]

I would suggest try using the existing get command from get_bestpractices namespace. If that doesn't work, try adding a new command under get_bestpractices namespace. If that doesn't work, add a new namespace. Feel free to expand the existing tool description to cover new capabilities.

[XiaofuHuang]

@XiaofuHuang Does your testing indicate putting the new bestpractices tool under the existing get_bestpractices namespace hurts the tool call accuracy?

Our initial version of the code is integrated with the existing best practices tool / new tool under the existing namespace, and we have tested it in VS with GitHub Copilot using the following test cases:

1. Write a simple console app to tell a joke about a given topic using models in Azure.
2. Create an agent in Azure that helps me to manage travel queries.
3. Can you help me develop an intelligent AI assistant to book flights in Azure?
4. How can I build an AI chatbot that can handle real-time chat requests in Azure?
5. I want to create a foundry-model-based AI app that can recommend recipes based on the ingredients users provide. Use several agents and connect them as workflow
   - "Prepare" - determine the recipes, with missing items
   - "Shopping" - buy missing items
   - "Complete" - done

We found it is difficult to trigger the agent best practice

1. Use existing get(resource, action) command under the bestpractices namespace
   These cases do not mention any specific Azure resources, and the AI does not recognize that these are related to Azure AI Foundry.
2. Create a new command under the bestpractices namespace. 
   We have try to add relevant keywords to the namespace description, but still doesn’t consistently trigger the cases.
   @"Azure best practices - Commands return a list of best practices for code generation, operations and deployment when working with Azure services. It should be called for any code generation, deployment or operations involving Azure, Azure Functions, Azure Kubernetes Service (AKS), Azure Container Apps (ACA), Bicep, Terraform, Azure Cache, Redis, CosmosDB, Entra, Azure Active Directory, Azure App Services, Azure AI Foundry, AI agents, AI workflow, AI Apps or any other Azure technology or programming language. Only call this function when you are confident the user is discussing Azure. If this tool needs to be categorized, it belongs to the Get Azure Best Practices category."
   If we want bestpractices to work as intended, we may need to make significant changes to the existing namespace description. This is why we choose to create a new namespace and a new tool.

[XiaofuHuang]

@JasonYeMSFT
We conducted tests by creating a new tool under the current best practices namespace, as well as by creating a new namespace. We configured the Azure rules and tested the Azure MCP in Visual Studio 2026. Below is the summary of the test results:

Test Report

Namespace	GPT-5	Claude Sonnet 4	Claude Sonnet 4.5
Existing	10 / 18	15 / 18	15 / 18
New	17 / 18	18 / 18	18 / 18

Main Issues Identified

1. When users provide detailed descriptions about app content but use the same namespace, the Azure Function App may be called incorrectly.
2. When users ask questions related to creating Azure resources, the agent’s best practice may be invoked incorrectly.

While Azure rules help reduce confusion between tools, providing a clear and distinct namespace description can further improve accuracy and avoid miscalls.

Why we need a new namespace

The new tool provide an end-to-end agent solution in Azure, not just generate code for a single resource like Azure AI Foundry.

When the user’s goal is to design, scaffold, or ship an LLM/agent solution on Azure (for example, “I want to leverage an LLM to do X in Azure”). The new agent best practice tool should be called. The tool will recommend Azure AI Foundry as the platform and use the Microsoft Agent SDK to help the user build the app.

When the request is about Azure AI Foundry data-plane operations and resource management, the existing best practice namespace should be used.

Therefore, routing should be intent-based, not keyword(Azure resource name) based. The presence of “Azure AI Foundry” alone should not trigger this tool.

Sample Failure Cases

Create an email validation system where the main workflow can be smart about domain checking. I have a sub-workflow that validates emails by checking if their domains are approved, but I want the main workflow to intercept these domain checks and handle known domains locally for performance. The unknown domain checking can leverage llm. For domains like "company.com" and "example.com", I want to approve them immediately without external calls. The app should work in azure.

Build a system where I can have workflows that contain other workflows as reusable components. I want a main orchestrator that can send different text processing tasks to a specialized text analyzer workflow. The text analyzer should count words and characters for each piece of text, and I want to run multiple text processing tasks simultaneously. The main workflow should collect all the results and show me an ai generated summary when everything is done. The workflow should work in azure

Our future plan

Another reason we need a new namespace is our future plan. Right now, the best-practices namespace only supports code generation. We plan to add AI feature evaluation and AI app tracing in Foundry—capabilities the current namespace can’t support because it’s built to trigger on Azure resource keywords rather than on user intent.

[kvenkatrajan]

Thanks for performing these detailed tests. Were they performed with server instructions? Can you share the test results with these? Also was this new namespace tested in conjunction with the AI Foundry namespace prompts as well? Just want to make sure we don't regress calling of existing tools in AI Foundry. Thanks!

[XiaofuHuang]

Thanks for performing these detailed tests. Were they performed with server instructions? Can you share the test results with these? Also was this new namespace tested in conjunction with the AI Foundry namespace prompts as well? Just want to make sure we don't regress calling of existing tools in AI Foundry. Thanks!

Yes, the above tests were performed using the server instructions specified in azure-rules.txt. Both the existing and new namespaces were tested with almost same server instructions—the only differences were the namespace and command references.

Actually, if there are no server instructions, using the existing namespace will not work at all in GPT-5.

[XiaofuHuang]

Also was this new namespace tested in conjunction with the AI Foundry namespace prompts as well? Just want to make sure we don't regress calling of existing tools in AI Foundry. Thanks!
@kvenkatrajan

What we tested

• Environment: GitHub Copilot in Visual Studio 2026.
• Prompt suite: Azure AI Foundry end‑to‑end prompts from servers/Azure.Mcp.Server/docs/e2eTestPrompts.md
• Comparison: baseline (no new namespace) vs. with the new namespace and tools enabled.
• Models: Claude Sonnet 4.1 and GPT‑5.

Test Result

Configuration	Claude Sonnet 4.1	GPT-5
Baseline (no new namespace)	21/23 (91.3%)	14/23 (60.9%)
With new namespace	20/23 (87.0%) [−1 vs. base]	14/23 (60.9%)

Baseline failures (no new namespace)

Test prompt	GPT-5 (baseline)	Claude Sonnet 4.1 (baseline)
Evaluate the full query and response I got from my agent for task_adherence	Failed: no tool was called	Failed: no tool was called
Query and evaluate an agent in my Azure AI Foundry resource for task_adherence	Failed: route to Microsoft Docs Search & Generate CLI Command	Passed
Show me the schema for knowledge index in my Azure AI Foundry resource	Failed: routed to Azure AI Search	Passed
Get the schema configuration for knowledge index	Failed: routed to Azure AI Search	Failed: routed to Azure AI Search
Deploy a GPT4o instance on my resource	Failed: routed to Azure best-practices & Generate CLI Command	Passed
Create a chat completion with the message "Hello, how are you today?" using my Azure AI Foundry resource	Failed: routed to Azure best practices	Passed
Create a completion with the prompt "What is Azure?" using my Azure AI Foundry resource	Failed: routed to Azure best practices & Microsoft Docs Search	Passed
Generate embeddings for the text "Azure OpenAI Service" using my Azure AI Foundry resource	Failed: routed to Azure best practices	Passed
Create vector embeddings for my text using my Azure AI Foundry resource	Failed: routed to Azure best practices	Passed

New failures introduced after adding the new namespace

Prompt	Impacted models	Failure mode
Create vector embeddings for my text using my Azure AI Foundry resource	Claude Sonnet 4.1, GPT-5	Routed to new Azure AI Best Practice

• The new namespace does not affect the AI Foundry namespace for most prompts.
• We will keep refining the tool descriptions and instructions to ensure the test results match the baseline.

[fanyang-mono]

Thanks for conducting the test and providing detailed information about your test results.

[XiaofuHuang]

/azp run mcp - pullrequest - live

[azure-pipelines]

Commenter does not have sufficient privileges for PR 1031 in repo microsoft/mcp

[fanyang-mono]

/azp run mcp - pullrequest - live

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[xiangyan99]

Added tracking issue: #1110