[Doc Gap] applens resource diagnose — required parameters changed to optional after tool design migration

[github-actions]

Documentation Gap

Server: Azure.Mcp.Server
Tool directory: tools/Azure.Mcp.Tools.AppLens
Triggered by: e908c69 (PR #2872) by @alzimmermsft
Changed files:

• tools/Azure.Mcp.Tools.AppLens/src/Commands/Resource/ResourceDiagnoseCommand.cs
• tools/Azure.Mcp.Tools.AppLens/src/Options/Resource/ResourceDiagnoseOptions.cs
• tools/Azure.Mcp.Tools.AppLens/src/Options/AppLensOptionDefinitions.cs (removed)

What Changed

PR #2872 migrated App Lens tools to the new tool design. During this migration, ResourceDiagnoseOptions was updated so that --subscription, --resource-group, and --resource-type became optional parameters (used only to disambiguate when multiple resources share the same name). Only --resource and --question remain required. A --tenant option was also added.

The command description now explicitly states: "Only the resource name and question are required — subscription, resource group, and resource type are optional and used to narrow down results when multiple resources share the same name."

Gaps Found

• azmcp-commands.md shows --subscription, --resource-group, and --resource-type as required (no brackets), but they are now optional
• azmcp-commands.md is missing the [--tenant] option
• The command signature in the docs no longer matches the actual MCP tool input schema

Files to Update

• servers/Azure.Mcp.Server/docs/azmcp-commands.md

Context

Current docs (incorrect):

# Diagnose resource using Azure App Lens
# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp applens resource diagnose --subscription <subscription> \
                                --resource-group <resource-group> \
                                --question <question> \
                                --resource-type <resource-type> \
                                --resource <resource>

Correct signature based on ResourceDiagnoseOptions.cs after #2872:

# Diagnose resource using Azure App Lens
# Only --resource and --question are required; all other parameters help disambiguate when multiple resources share the same name
# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp applens resource diagnose --resource <resource> \
                                --question <question> \
                                [--subscription <subscription>] \
                                [--resource-group <resource-group>] \
                                [--resource-type <resource-type>] \
                                [--tenant <tenant>]

📐 Implementation Guide

This section contains step-by-step instructions for a coding agent to implement the changes described above.

Step 1: Modify files

File: servers/Azure.Mcp.Server/docs/azmcp-commands.md

Find and replace the existing App Lens diagnose command block:

Old:

# Diagnose resource using Azure App Lens
# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp applens resource diagnose --subscription <subscription> \
                                --resource-group <resource-group> \
                                --question <question> \
                                --resource-type <resource-type> \
                                --resource <resource>

New:

# Diagnose resource using Azure App Lens
# Only --resource and --question are required; subscription, resource-group, and resource-type are optional and used to narrow down results when multiple resources share the same name
# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp applens resource diagnose --resource <resource> \
                                --question <question> \
                                [--subscription <subscription>] \
                                [--resource-group <resource-group>] \
                                [--resource-type <resource-type>] \
                                [--tenant <tenant>]

Step 2: Verify documentation structure

servers/Azure.Mcp.Server/docs/azmcp-commands.md — must include:

• A global options table at the top (subscription, resource-group, tenant, retry-max-retries, retry-delay)
• One ## azmcp <service> <resource> <operation> section per command, containing a description, parameters table, and example usage block

Step 3: Validate

Run these commands in order. Each must succeed before proceeding to the next:

1. dotnet build servers/Azure.Mcp.Server/ — confirms the server project compiles cleanly
2. dotnet build tools/Azure.Mcp.Tools.AppLens/src/ — confirms the AppLens toolset compiles
3. .\eng\common\spelling\Invoke-Cspell.ps1 — checks spelling in new or modified documentation

Next Steps

Tip

Ready for automated implementation? Assign this issue to @copilot to have Copilot coding agent implement the changes described in the Implementation Guide above

Generated by Documentation Updater · ● 14.4M · ◷