Add --namespaces switch to azmcp tools list and update ToolDescriptionEvaluator to work with namespaces/consolidated modes

core/Azure.Mcp.Core/src/Areas/Tools/Commands/ToolsListCommand.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+using System.CommandLine;
 using Azure.Mcp.Core.Commands;
 using Azure.Mcp.Core.Models.Option;
 using Microsoft.Extensions.Logging;
@@ -11,6 +12,10 @@ namespace Azure.Mcp.Core.Areas.Tools.Commands;
 public sealed class ToolsListCommand(ILogger<ToolsListCommand> logger) : BaseCommand<EmptyOptions>
 {
     private const string CommandTitle = "List Available Tools";
+    private static readonly Option<bool> NamespacesOption = new("--namespaces")
+    {
+        Description = "If specified, returns a list of top-level service namespaces instead of individual commands.",
+    };
 
     public override string Name => "list";
 
@@ -33,23 +38,124 @@ arguments. Use this to explore the CLI's functionality or to build interactive c
         Secret = false
     };
 
+    protected override void RegisterOptions(Command command)
+    {
+        command.Options.Add(NamespacesOption);
+    }
+
     protected override EmptyOptions BindOptions(ParseResult parseResult) => new();
 
     public override async Task<CommandResponse> ExecuteAsync(CommandContext context, ParseResult parseResult)
     {
         try
         {
             var factory = context.GetService<CommandFactory>();
+
+            // If the --namespaces flag set, return distinct top-level namespaces (area group names beneath root 'azmcp')
+            var namespacesOnly = parseResult.CommandResult.HasOptionResult(NamespacesOption);
+            if (namespacesOnly)
+            {
+                // Exclude internal or special namespaces. 'extension' is flattened as top-level leaf commands.
+                var ignored = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "server", "tools" };
+                var rootGroup = factory.RootGroup; // azmcp
+
+                // Build lookup for namespace descriptions from the existing registered groups
+                var namespaceDescriptionMap = rootGroup.SubGroup.ToDictionary(commandGroup => commandGroup.Name, g => g.Description, StringComparer.OrdinalIgnoreCase);
+
+                // Single pass over all visible commands to bucket by namespace
+                var namespaceBuckets = new Dictionary<string, List<CommandInfo>>(StringComparer.OrdinalIgnoreCase);
+                var extensionLeafCommands = new List<CommandInfo>();
+
+                foreach (var kvp in CommandFactory.GetVisibleCommands(factory.AllCommands))
+                {
+                    var key = kvp.Key; // Tokenized e.g. azmcp_storage_account_get
+                    var firstSeparatorIndex = key.IndexOf(CommandFactory.Separator); // Expect at least root + namespace + verb
+
+                    if (firstSeparatorIndex < 0)
+                        continue; // Malformed, skip
+
+                    var secondSeparatorIndex = key.IndexOf(CommandFactory.Separator, firstSeparatorIndex + 1);
+
+                    if (secondSeparatorIndex < 0)
+                        continue; // Not enough tokens
+
+                    var namespaceToken = key.Substring(firstSeparatorIndex + 1, secondSeparatorIndex - firstSeparatorIndex - 1);
+
+                    if (ignored.Contains(namespaceToken))
+                    {
+                        // Skip internal groups entirely
+                        continue;
+                    }
+
+                    var cmdInfo = CreateCommand(key, kvp.Value);
+
+                    if (namespaceToken.Equals("extension", StringComparison.OrdinalIgnoreCase))
+                    {
+                        // Flatten: treat each extension command as top-level leaf
+                        extensionLeafCommands.Add(cmdInfo);
+
+                        continue;
+                    }
+
+                    if (!namespaceBuckets.TryGetValue(namespaceToken, out var list))
+                    {
+                        list = new List<CommandInfo>();
+                        namespaceBuckets[namespaceToken] = list;
+                    }
+
+                    list.Add(cmdInfo);
+                }
+
+                // Build namespace CommandInfo objects
+                var namespaceCommands = namespaceBuckets
+                    .Select(kvp =>
+                    {
+                        var namespaceName = kvp.Key;
+                        var subcommands = kvp.Value
+                            .OrderBy(ci => ci.Command, StringComparer.OrdinalIgnoreCase)
+                            .ToList();
+                        namespaceDescriptionMap.TryGetValue(namespaceName, out var desc);
+                        return new CommandInfo
+                        {
+                            Name = namespaceName,
+                            Description = desc ?? string.Empty,
+                            Command = $"azmcp {namespaceName}",
+                            Subcommands = subcommands,
+                            Options = null,
+                            SubcommandsCount = subcommands.Count
+                        };
+                    })
+                    .OrderBy(ci => ci.Name, StringComparer.OrdinalIgnoreCase)
+                    .ToList();
+
+                // Order extension leaf commands
+                extensionLeafCommands = extensionLeafCommands
+                    .OrderBy(ci => ci.Command, StringComparer.OrdinalIgnoreCase)
+                    .ToList();
+
+                // Combine and sort: namespaces first, then extension leaves by Name
+                namespaceCommands.AddRange(extensionLeafCommands);
+                namespaceCommands = namespaceCommands
+                    .OrderByDescending(ci => ci.SubcommandsCount > 0)
+                    .ThenBy(ci => ci.Name, StringComparer.OrdinalIgnoreCase)
+                    .ToList();
+
+                context.Response.Results = ResponseResult.Create(namespaceCommands, ModelsJsonContext.Default.ListCommandInfo);
+                context.Response.ResultsCount = namespaceCommands.Count;
+                return context.Response;
+            }
+
             var tools = await Task.Run(() => CommandFactory.GetVisibleCommands(factory.AllCommands)
                 .Select(kvp => CreateCommand(kvp.Key, kvp.Value))
                 .ToList());
 
             context.Response.Results = ResponseResult.Create(tools, ModelsJsonContext.Default.ListCommandInfo);
+            context.Response.ResultsCount = tools.Count;
             return context.Response;
         }
         catch (Exception ex)
         {
-            logger.LogError(ex, "An exception occurred processing tool.");
+            logger.LogError(ex, "An exception occurred while processing tool listing.");
             HandleException(context, ex);
 
             return context.Response;
@@ -73,6 +179,8 @@ private static CommandInfo CreateCommand(string tokenizedName, IBaseCommand comm
             Description = commandDetails.Description ?? string.Empty,
             Command = tokenizedName.Replace(CommandFactory.Separator, ' '),
             Options = optionInfos,
+            // Leaf commands have no subcommands.
+            SubcommandsCount = 0,
         };
     }
 }

core/Azure.Mcp.Core/src/Models/Command/CommandInfo.cs

@@ -24,4 +24,10 @@ public class CommandInfo
     [JsonPropertyName("option")]
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public List<OptionInfo>? Options { get; set; }
+
+    // Number of immediate subcommands for grouping/namespace entries.
+    // Leaf commands will always have 0.
+    [JsonPropertyName("subcommandsCount")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
+    public int SubcommandsCount { get; set; }
 }

core/Azure.Mcp.Core/src/Models/Command/CommandResponse.cs

@@ -22,6 +22,12 @@ public class CommandResponse
 
     [JsonPropertyName("duration")]
     public long Duration { get; set; }
+
+    // Number of top-level result items (length of the deserialized results collection if a collection is returned).
+    // Set explicitly by commands that know the concrete collection size.
+    [JsonPropertyName("resultsCount")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
+    public int ResultsCount { get; set; }
 }
 
 [JsonConverter(typeof(ResultConverter))]

core/Azure.Mcp.Core/tests/Azure.Mcp.Core.UnitTests/Areas/Tools/UnitTests/ToolsListCommandTests.cs

@@ -74,6 +74,8 @@ public async Task ExecuteAsync_WithValidContext_ReturnsCommandInfoList()
         Assert.NotNull(result);
         Assert.NotEmpty(result);
 
+        Assert.Equal(result.Count, response.ResultsCount);
+
         foreach (var command in result)
         {
             Assert.False(string.IsNullOrWhiteSpace(command.Name), "Command name should not be empty");
@@ -82,6 +84,9 @@ public async Task ExecuteAsync_WithValidContext_ReturnsCommandInfoList()
 
             Assert.StartsWith("azmcp ", command.Command);
 
+            // Leaf commands: subcommandsCount should always be 0
+            Assert.Equal(0, command.SubcommandsCount);
+
             if (command.Options != null && command.Options.Count > 0)
             {
                 foreach (var option in command.Options)
@@ -118,6 +123,7 @@ public async Task ExecuteAsync_JsonSerializationStressTest_HandlesLargeResults()
         // Verify JSON round-trip preserves all data
         var serializedJson = JsonSerializer.Serialize(result);
         Assert.Equal(json, serializedJson);
+        Assert.Equal(result.Count, response.ResultsCount);
     }
 
     /// <summary>
@@ -145,6 +151,8 @@ public async Task ExecuteAsync_WithValidContext_FiltersHiddenCommands()
 
         Assert.Contains(result, cmd => !string.IsNullOrEmpty(cmd.Name));
 
+        Assert.Equal(result.Count, response.ResultsCount);
+
     }
 
     /// <summary>
@@ -244,6 +252,8 @@ public async Task ExecuteAsync_ReturnsSpecificKnownCommands()
         Assert.NotNull(result);
         Assert.NotEmpty(result);
 
+        Assert.Equal(result.Count, response.ResultsCount);
+
         Assert.True(result.Count >= MinimumExpectedCommands, $"Expected at least {MinimumExpectedCommands} commands, got {result.Count}");
 
         var allCommands = result.Select(cmd => cmd.Command).ToList();
@@ -300,6 +310,8 @@ public async Task ExecuteAsync_CommandPathFormattingIsCorrect()
 
         Assert.NotNull(result);
 
+        Assert.Equal(result.Count, response.ResultsCount);
+
         foreach (var command in result)
         {
             // Command paths should not start or end with spaces
@@ -311,6 +323,104 @@ public async Task ExecuteAsync_CommandPathFormattingIsCorrect()
         }
     }
 
+    /// <summary>
+    /// Verifies that the --namespaces switch returns only distinct top-level namespaces.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_WithNamespaceSwitch_ReturnsNamespacesOnly()
+    {
+        // Arrange
+        var args = _commandDefinition.Parse(new[] { "--namespaces" });
+
+        // Act
+        var response = await _command.ExecuteAsync(_context, args);
+
+        // Assert
+        Assert.NotNull(response);
+        Assert.NotNull(response.Results);
+
+        // Serialize then deserialize as list of CommandInfo
+        var json = JsonSerializer.Serialize(response.Results);
+        var namespaces = JsonSerializer.Deserialize<List<CommandInfo>>(json);
+
+        Assert.NotNull(namespaces);
+        Assert.NotEmpty(namespaces);
+
+        Assert.Equal(namespaces!.Count, response.ResultsCount);
+
+        // Should include some well-known namespaces (matching Name property)
+        Assert.Contains(namespaces, ci => ci.Name.Equals("subscription", StringComparison.OrdinalIgnoreCase));
+        Assert.Contains(namespaces, ci => ci.Name.Equals("storage", StringComparison.OrdinalIgnoreCase));
+        Assert.Contains(namespaces, ci => ci.Name.Equals("keyvault", StringComparison.OrdinalIgnoreCase));
+
+        bool foundNamespaceWithSubcommands = false;
+        bool foundSubcommandWithOptions = false;
+
+        foreach (var ns in namespaces!)
+        {
+            Assert.False(string.IsNullOrWhiteSpace(ns.Name));
+            Assert.False(string.IsNullOrWhiteSpace(ns.Command));
+            Assert.StartsWith("azmcp ", ns.Command, StringComparison.OrdinalIgnoreCase);
+            Assert.Equal(ns.Name, ns.Name.Trim());
+            Assert.DoesNotContain(" ", ns.Name);
+            // Namespace should not itself have options
+            Assert.Null(ns.Options);
+            // Count should equal number of subcommands for namespaces
+            Assert.Equal(ns.Subcommands?.Count ?? 0, ns.SubcommandsCount);
+
+            if (ns.Subcommands is { Count: > 0 })
+            {
+                foundNamespaceWithSubcommands = true;
+                // Validate a few subcommands
+                foreach (var sub in ns.Subcommands.Take(5))
+                {
+                    Assert.False(string.IsNullOrWhiteSpace(sub.Name));
+                    Assert.False(string.IsNullOrWhiteSpace(sub.Command));
+                    Assert.StartsWith($"azmcp {ns.Name} ", sub.Command, StringComparison.OrdinalIgnoreCase);
+                    // Subcommand entries are leaf commands; count must be 0
+                    Assert.Equal(0, sub.SubcommandsCount);
+
+                    if (sub.Options != null && sub.Options.Count > 0)
+                    {
+                        foundSubcommandWithOptions = true;
+                    }
+                }
+            }
+        }
+
+        Assert.True(foundNamespaceWithSubcommands, "Expected at least one namespace to contain subcommands.");
+        Assert.True(foundSubcommandWithOptions, "Expected at least one subcommand to include options.");
+    }
+
+    /// <summary>
+    /// Explicitly verifies that count reflects subcommand counts for namespaces and 0 for their leaf subcommands.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Namespaces_CountMatchesSubcommandCounts()
+    {
+        var args = _commandDefinition.Parse(new[] { "--namespaces" });
+        var response = await _command.ExecuteAsync(_context, args);
+
+        Assert.NotNull(response.Results);
+
+        var namespaces = DeserializeResults(response.Results);
+
+        Assert.NotEmpty(namespaces);
+        Assert.Equal(namespaces.Count, response.ResultsCount);
+
+        foreach (var ns in namespaces.Take(10))
+        {
+            Assert.Equal(ns.Subcommands?.Count ?? 0, ns.SubcommandsCount);
+            if (ns.Subcommands != null)
+            {
+                foreach (var sub in ns.Subcommands)
+                {
+                    Assert.Equal(0, sub.SubcommandsCount);
+                }
+            }
+        }
+    }
+
     /// <summary>
     /// Verifies that the command handles empty command factory gracefully
     /// and returns empty results when no commands are available.
@@ -350,6 +460,7 @@ public async Task ExecuteAsync_WithEmptyCommandFactory_ReturnsEmptyResults()
 
         Assert.NotNull(result);
         Assert.Empty(result); // Should be empty when no commands are available
+        Assert.Equal(result.Count, response.ResultsCount);
     }
 
     /// <summary>

docs/azmcp-commands.md

@@ -869,6 +869,9 @@ azmcp bestpractices get --resource <resource> --action <action>
 ```bash
 # List all available tools in the Azure MCP server
 azmcp tools list
+
+# List only the available top-level service namespaces
+azmcp tools list --namespaces
 ```
 
 ### Azure Monitor Operations
@@ -1397,6 +1400,21 @@ All responses follow a consistent JSON format:
 }
 ```
 
+### Tool & Namespace Result Objects
+
+When invoking `azmcp tools list` (with or without `--namespaces`), each returned object now includes a `count` field:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Command or namespace name |
+| `description` | Human-readable description |
+| `command` | Fully qualified CLI invocation path |
+| `subcommands` | (Namespaces only) Array of leaf command objects |
+| `option` | (Leaf commands only) Array of options supported by the command |
+| `count` | Namespaces: number of subcommands; Leaf commands: always 0 (options not counted) |
+
+This quantitative field enables quick sizing of a namespace without traversing nested arrays. Leaf command complexity should be inferred from its option list, not the `count` field.
+
 ## Error Handling
 
 The CLI returns structured JSON responses for errors, including:

docs/e2eTestPrompts.md

@@ -290,8 +290,6 @@ This file contains prompts used for end-to-end testing to ensure each tool is in
 | azmcp_bestpractices_get | Get the latest Azure Functions best practices |
 | azmcp_bestpractices_get | Get the latest Azure Static Web Apps best practices |
 | azmcp_bestpractices_get | What are azure function best practices? |
-| azmcp_bestpractices_get | Create the plan for creating a simple HTTP-triggered function app in javascript that returns a random compliment from a predefined list in a JSON response. And deploy it to azure eventually. But don't create any code until I confirm. |
-| azmcp_bestpractices_get | Create the plan for creating a to-do list app. And deploy it to azure as a container app. But don't create any code until I confirm. |
 
 ## Azure Monitor