[Doc Gap] applicationinsights_recommendation_list — global options table incorrectly claims --auth-method applies to all commands after PR [Content truncated due to length]

[github-actions]

Documentation Gap

Server: Azure.Mcp.Server
Tool directory: tools/Azure.Mcp.Tools.ApplicationInsights
Triggered by: commit 35bff42 / PR #2874 by @alzimmermsft
Changed files:

• tools/Azure.Mcp.Tools.ApplicationInsights/src/Commands/Recommendation/RecommendationListCommand.cs
• tools/Azure.Mcp.Tools.ApplicationInsights/src/Options/RecommendationListOptions.cs

What Changed

PR #2874 migrated RecommendationListCommand from the old tool design (SubscriptionCommand<RecommendationListOptions> with GlobalOptions base) to the new two-type-parameter design (SubscriptionCommand<RecommendationListOptions, RecommendationListCommandResult>). RecommendationListOptions was changed from extending SubscriptionOptions (which inherits GlobalOptions → includes --auth-method) to implementing ISubscriptionOption directly with only explicit [Option] attributes.

This is a breaking change documented in the changelog entry added by the PR:

changes:
  - section: "Breaking Changes"
    description: "Removed unused parameters from Application Insights tools."

The removed option is --auth-method (and the AuthMethod property formerly inherited via GlobalOptions).

Gaps Found

• azmcp-commands.md Global Options table states "The following options are available for all commands" and lists --auth-method. However, applicationinsights recommendation list is now an exception that does not accept --auth-method. The global options section needs to be updated to list applicationinsights recommendation list as an exception, consistent with the same fix needed for cloudarchitect design (tracked in [Doc Gap] cloudarchitect_design tool — docs show removed global options and wrong --state parameter #2827) and acr registry list / acr registry repository list (tracked in [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).

Files to Update

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

Context

Before the migration, the option inheritance chain was:

RecommendationListCommand → SubscriptionCommand (old) → GlobalCommand
                                                         └── registers --auth-method

After the migration:

RecommendationListCommand → SubscriptionCommand (new) → AuthenticatedCommand → BaseCommand
                                                                (no --auth-method registered)

The new RecommendationListOptions explicitly declares only: Tenant, Subscription, ResourceGroup, RetryPolicy.

The current global options section in azmcp-commands.md (unchanged by PR #2874):

## Global Options

The following options are available for all commands:

| Option | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--subscription` | No | Environment variable `AZURE_SUBSCRIPTION_ID` | Azure subscription ID for target resources |
| `--tenant-id` | No | - | Azure tenant ID for authentication |
| `--auth-method` | No | 'credential' | Authentication method ('credential', 'key', 'connectionString') |
...

📐 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

Locate the Global Options section. If a "Note" or exception list already exists (from the fix for issues #2827 and/or #2845), extend it to include applicationinsights recommendation list:

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

If no such note exists yet (issues #2827 and #2845 are unresolved), create it after the Global Options table with all three exceptions included.

Step 2: Verify documentation structure

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

• The Global Options section note (or a new note) lists applicationinsights recommendation list as an exception to --auth-method
• The Application Insights section command signatures remain accurate (they already correctly show --subscription and optional --resource-group)

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.ApplicationInsights/src/ — confirms the Application Insights toolset compiles
3. dotnet test tools/Azure.Mcp.Tools.ApplicationInsights/tests/Azure.Mcp.Tools.ApplicationInsights.Tests/ --filter "TestType!=Live" — runs unit tests for the affected toolset
4. .\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 · ● 11.5M · ◷