[Doc Gap] applens_resource_diagnose, aks_cluster_get, aks_nodepool_get — global options table incorrectly claims --auth-method applies to [Content truncated due to length]

[github-actions]

Documentation Gap

Server: Azure.Mcp.Server
Tool directory: tools/Azure.Mcp.Tools.AppLens, tools/Azure.Mcp.Tools.Aks
Triggered by: commit e908c693a7 / PR #2872 and commit af48272c43 / PR #2868 by @alzimmermsft
Changed files:

• tools/Azure.Mcp.Tools.AppLens/src/Commands/Resource/ResourceDiagnoseCommand.cs
• tools/Azure.Mcp.Tools.AppLens/src/Options/AppLensOptionDefinitions.cs (deleted)
• tools/Azure.Mcp.Tools.AppLens/src/Options/Resource/ResourceDiagnoseOptions.cs
• tools/Azure.Mcp.Tools.Aks/src/Commands/Cluster/ClusterGetCommand.cs
• tools/Azure.Mcp.Tools.Aks/src/Commands/Nodepool/NodepoolGetCommand.cs
• tools/Azure.Mcp.Tools.Aks/src/Options/AksOptionDefinitions.cs (deleted)
• tools/Azure.Mcp.Tools.Aks/src/Options/BaseAksOptions.cs (deleted)
• tools/Azure.Mcp.Tools.Aks/src/Options/Cluster/ClusterGetOptions.cs
• tools/Azure.Mcp.Tools.Aks/src/Options/Nodepool/NodepoolGetOptions.cs

What Changed

PR #2872 (App Lens) and PR #2868 (AKS) both migrated their tools from the old tool design (inheriting from GlobalCommand / BaseAksCommand which extended SubscriptionCommand → GlobalCommand) to the new two-type-parameter SubscriptionCommand/BaseCommand design. Both migrations are breaking changes that removed --auth-method (and in App Lens, also --retry-*) from the affected tools.

Changelog entries confirm the breaking changes:

• PR Migrate App Lens tools to new tool design #2872: "Removed unused parameters from App Lens tools."
• PR Migrate AKS tools to new tool design #2868: "Removed auth mode from aks_cluster_get and aks_nodepool_get tools as they don't use that parameter."

Additionally, the PR #2872 migration explicitly formalized that --question and --resource are required for applens resource diagnose (using the C# required keyword), while --subscription, --resource-group, and --resource-type are optional — but this optionality distinction is not reflected in the command documentation.

Gaps Found

• azmcp-commands.md Global Options table states "The following options are available for all commands" and lists --auth-method. After PR Migrate App Lens tools to new tool design #2872, applens resource diagnose does not support --auth-method. After PR Migrate AKS tools to new tool design #2868, aks cluster get and aks nodepool get do not support --auth-method. The global options section needs an exceptions note (consistent with [Doc Gap] cloudarchitect_design tool — docs show removed global options and wrong --state parameter #2827, [Doc Gap] acr_registry_list and acr_registry_repository_list — global options table incorrectly claims --auth-method applies to all comman [Content truncated due to length] #2845, and [Doc Gap] applicationinsights_recommendation_list — global options table incorrectly claims --auth-method applies to all commands after PR [Content truncated due to length] #2899) listing these tools.

• azmcp-commands.md App Lens command signature currently shows all five parameters without brackets (implying all are required):

  azmcp applens resource diagnose --subscription <subscription> \
                                  --resource-group <resource-group> \
                                  --question <question> \
                                  --resource-type <resource-type> \
                                  --resource <resource>

  But only --question and --resource are required; --subscription, --resource-group, and --resource-type are optional (PR Migrate App Lens tools to new tool design #2872 explicitly made this clear by using required string for the mandatory ones and string? for the optional ones). The command description itself says: "Only the resource name and question are required."

Files to Update

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

Context

App Lens — before migration (PR #2872):

ResourceDiagnoseCommand → GlobalCommand<ResourceDiagnoseOptions>
                          └── registers --auth-method, --retry-*, --tenant-id

// Old AppLensOptionDefinitions.cs (deleted):
public static readonly Option<string?> Subscription = new("--subscription") { Required = false };
public static readonly Option<string?> ResourceGroup = new("--resource-group") { Required = false };
public static readonly Option<string?> ResourceType  = new("--resource-type")  { Required = false };
public static readonly Option<string>  Resource      = new("--resource")       { Required = true  };
public static readonly Option<string>  Question      = new("--question")       { Required = true  };

App Lens — after migration:

ResourceDiagnoseCommand → BaseCommand<ResourceDiagnoseOptions, ResourceDiagnoseCommandResult>
                          (no --auth-method, no --retry-* registered)

// New ResourceDiagnoseOptions.cs:
[Option(OptionDescriptions.Tenant)]         public string? Tenant        { get; set; }  // optional
[Option("Azure resource group name...")]    public string? ResourceGroup { get; set; }  // optional
[Option("User question")]                   public required string Question { get; set; } // REQUIRED
[Option("The name of the resource...")]     public required string Resource { get; set; } // REQUIRED
[Option("Resource type...")]                public string? ResourceType  { get; set; }  // optional
[Option("Azure subscription ID...")]        public string? Subscription  { get; set; }  // optional

AKS — before migration (PR #2868):

ClusterGetCommand/NodepoolGetCommand → BaseAksCommand → SubscriptionCommand (old) → GlobalCommand
                                                                                      └── registers --auth-method

AKS — after migration:

ClusterGetCommand/NodepoolGetCommand → SubscriptionCommand (new) → AuthenticatedCommand → BaseCommand
                                                                    (no --auth-method registered)

📐 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

Change 1 — Global Options exceptions note:

After the Global Options table (around line 20), add or extend the exceptions note to include the App Lens and AKS tools. If a note already exists (from fixes for #2827, #2845, or #2899), append to it:

Note: The following commands do not support --auth-method (and other global options where noted):

• cloudarchitect design — does not support --subscription, --tenant-id, --auth-method, or any --retry-* options
• acr registry list and acr registry repository list — do not support --auth-method
• applicationinsights recommendation list — does not support --auth-method
• applens resource diagnose — does not support --auth-method or any --retry-* options
• aks cluster get and aks nodepool get — do not support --auth-method

Change 2 — App Lens command signature (around line 554–564):

Replace the current App Lens command signature with one that correctly brackets the optional parameters:

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

Step 2: Verify documentation structure

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

• The Global Options section note lists applens resource diagnose, aks cluster get, and aks nodepool get as exceptions to --auth-method
• The App Lens command signature correctly uses [] brackets for optional parameters (--subscription, --resource-group, --resource-type) and no brackets for required ones (--question, --resource)
• The AKS command signatures remain accurate (they already correctly show --subscription, --resource-group, --cluster, [--nodepool])

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 App Lens toolset compiles
3. dotnet build tools/Azure.Mcp.Tools.Aks/src/ — confirms the AKS toolset compiles
4. .\eng\common\spelling\Invoke-Cspell.ps1 — checks spelling in 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 · ● 15.5M · ◷