[Doc Gap] cloudarchitect_design tool — docs show removed global options and wrong `--state` parameter

[github-actions]

Documentation Gap

Server: Azure.Mcp.Server
Tool directory: tools/Azure.Mcp.Tools.CloudArchitect
Triggered by: commit 7eec066 / PR #2822 by @alzimmermsft
Changed files:

• tools/Azure.Mcp.Tools.CloudArchitect/src/Commands/Design/DesignCommand.cs
• tools/Azure.Mcp.Tools.CloudArchitect/src/Options/ArchitectureDesignToolOptions.cs

What Changed

PR #2822 changed DesignCommand from extending GlobalCommand<ArchitectureDesignToolOptions> to BaseCommand<ArchitectureDesignToolOptions>. This is a breaking change that removed the following options from cloudarchitect_design:

• --subscription
• --resource-group
• --tenant-id
• --auth-method
• --retry-max-retries, --retry-delay, --retry-max-delay, --retry-mode, --retry-network-timeout

These options were never used by the tool and are no longer accepted.

Gaps Found

• azmcp-commands.md global options table still states "The following options are available for all commands" — but cloudarchitect design is now an exception and does not accept subscription, tenant-id, auth-method, or any retry-* options.
• azmcp-commands.md Cloud Architect command signature shows --architecture-component as a valid option, but the code (DesignCommand.RegisterOptions) never registers that option. The actual 7th parameter registered is --state (for passing the serialized architecture state JSON). The docs should show --state instead of --architecture-component.

Files to Update

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

Context

Changelog entry added by the PR:

changes:
  - section: "Breaking Changes"
    description: "Removed resource group, tenant, auth method, and retry options from cloudarchitect_design tool as they aren't used."

Current (incorrect) Cloud Architect section in azmcp-commands.md:

# Design Azure cloud architectures through guided questions
azmcp cloudarchitect design [--question <question>] \
                            [--question-number <question-number>] \
                            [--total-questions <total-questions>] \
                            [--answer <answer>] \
                            [--next-question-needed <true/false>] \
                            [--confidence-score <confidence-score>] \
                            [--architecture-component <architecture-component>]  ← wrong, should be --state

Actual registered options in DesignCommand.RegisterOptions:

command.Options.Add(CloudArchitectOptionDefinitions.Question);
command.Options.Add(CloudArchitectOptionDefinitions.QuestionNumber);
command.Options.Add(CloudArchitectOptionDefinitions.TotalQuestions);
command.Options.Add(CloudArchitectOptionDefinitions.Answer);
command.Options.Add(CloudArchitectOptionDefinitions.NextQuestionNeeded);
command.Options.Add(CloudArchitectOptionDefinitions.ConfidenceScore);
command.Options.Add(CloudArchitectOptionDefinitions.State);  // ← --state, not --architecture-component

📐 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

Two edits are needed:

Edit 1 — Fix the Cloud Architect command signature (replace --architecture-component with --state):

Find:

azmcp cloudarchitect design [--question <question>] \
                            [--question-number <question-number>] \
                            [--total-questions <total-questions>] \
                            [--answer <answer>] \
                            [--next-question-needed <true/false>] \
                            [--confidence-score <confidence-score>] \
                            [--architecture-component <architecture-component>]

Replace with:

azmcp cloudarchitect design [--question <question>] \
                            [--question-number <question-number>] \
                            [--total-questions <total-questions>] \
                            [--answer <answer>] \
                            [--next-question-needed <true/false>] \
                            [--confidence-score <confidence-score>] \
                            [--state <state>]

Edit 2 — Update the Global Options table intro to note that cloudarchitect design does not accept global options:

In the Global Options section, add a note after the table (or as a note before/after the table) similar to:

Note: The cloudarchitect design command is a local, stateless tool and does not support --subscription, --tenant-id, --auth-method, or any --retry-* options.

Step 2: Verify documentation structure

servers/Azure.Mcp.Server/docs/azmcp-commands.md — confirm the Cloud Architect section:

• Shows the corrected command signature with --state
• Global options section has a note or qualifier indicating that cloudarchitect design is exempt from global options

Step 3: Validate

Run these commands in order:

1. dotnet build tools/Azure.Mcp.Tools.CloudArchitect/src/ — confirms the toolset compiles cleanly
2. .\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 · ● 6.6M · ◷