Reduce AppLens failures (#2018)

* Reduce AppLens failures

The "diagnose" tool uses an AppLens endpoint to identify problems in Azure resources and provide solutions. It currently has a high failure rate. I suspect this is due in part to the way we present the parameters to the LM and how we handle them internally. The subscription, resource group, and resource type are presented as optional parameters, when in fact we need them all to construct the resource ID to pass to the AppLens API. It is likely that the LMs first attempt at diagnosing an issue will thus result in a failure, with a message telling it what it needs to provide. At that point it _may_ be able to find the necessary information, but it might also hallucinate it (leading to further failures) or just give up on the tool entirely.

Instead, we should treat only the resource name as required, and then use an Azure Resource Graph query to find all of the potentially relevant resources. The subscription, group, and type can then be used to disambiguate when more than one possibility is found. This should increase the likelihood of finding the expected resource on the first try.

* Add a changelog entry

* Add trailing newline

* Remove unnecessary filter

The `AppLensService` currently uses ARG to find all resources of a given name, and then filters those results by subscription, resource group, and resource type, if they have been provided. Since the ARG query results are broad we have the opportunity to do some error correction; e.g., if resource group is given _but_ the resource is actually in a different group we will still find it and can return a message asking the LM if that's actually the one it meant.

However, if we have a subscription we pass it in to the ARG query and results will necessarily be limited to that subscription; there is no value in further filtering. Here we remove the unncessary code.

Author: tmeschter

servers/Azure.Mcp.Server/changelog-entries/1773334143313.yaml

@@ -0,0 +1,4 @@
+pr: 2018
+changes:
+  - section: "Bugs Fixed"
+    description: "Improved AppLens diagnose tool to use ARG-based resource discovery with optional subscription, resource group, and resource type parameters"

tools/Azure.Mcp.Tools.AppLens/src/Commands/Resource/ResourceDiagnoseCommand.cs

@@ -1,24 +1,24 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using Azure.Mcp.Core.Commands.Subscription;
-using Azure.Mcp.Core.Models.Option;
+using Azure.Mcp.Core.Commands;
 using Azure.Mcp.Tools.AppLens.Models;
 using Azure.Mcp.Tools.AppLens.Options;
 using Azure.Mcp.Tools.AppLens.Options.Resource;
 using Azure.Mcp.Tools.AppLens.Services;
 using Microsoft.Extensions.Logging;
 using Microsoft.Mcp.Core.Commands;
 using Microsoft.Mcp.Core.Models.Command;
-using Microsoft.Mcp.Core.Models.Option;
 
 namespace Azure.Mcp.Tools.AppLens.Commands.Resource;
 
 /// <summary>
 /// Command to diagnose Azure resources using AppLens conversational diagnostics.
+/// Subscription, resource group, and resource type are optional - the service uses
+/// Azure Resource Graph to discover the resource by name when they are not provided.
 /// </summary>
 public sealed class ResourceDiagnoseCommand(ILogger<ResourceDiagnoseCommand> logger, IAppLensService appLensService)
-    : SubscriptionCommand<ResourceDiagnoseOptions>
+    : GlobalCommand<ResourceDiagnoseOptions>
 {
     private const string CommandTitle = "Diagnose Azure Resource Issues";
     private readonly ILogger<ResourceDiagnoseCommand> _logger = logger;
@@ -29,9 +29,10 @@ public sealed class ResourceDiagnoseCommand(ILogger<ResourceDiagnoseCommand> log
     public override string Name => "diagnose";
 
     public override string Description =>
-    "Get diagnostic help from App Lens for Azure application and service issues to identify what’s wrong with a service. Ask questions about performance, slowness, failures, errors, application state, availability to receive expert analysis and solutions which can help when performing diagnostics and to address issues about performance and failures. " +
-    "Returns insights, recommended solutions, and analysis. " +
-    "Always use this tool before manually checking metrics or logs when users report performance or functionality issues. Use Azure CLI to find the subscription, resourceGroup, and resourceType if not provided. If given a resourceId, parse it to extract subscription, resourceGroup, and resourceType (format: /subscriptions/{subscription}/resourceGroups/{resourceGroup}/providers/{resourceType}/{resource}). This tool can be used to ask questions about application state, diagnose performance problems, and address service failures.";
+    "Get diagnostic help from App Lens for Azure application and service issues to identify what's wrong with a service. Ask questions about performance, slowness, failures, errors, application state, availability to receive expert analysis and solutions which can help when performing diagnostics and to address issues about performance and failures. " +
+    "Returns analysis, insights, and recommended solutions. " +
+    "Always use this tool before manually checking metrics or logs when users report performance or functionality issues. " +
+    "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.";
     public override string Title => CommandTitle;
 
     public override ToolMetadata Metadata => new()
@@ -47,19 +48,21 @@ public sealed class ResourceDiagnoseCommand(ILogger<ResourceDiagnoseCommand> log
     protected override void RegisterOptions(Command command)
     {
         base.RegisterOptions(command);
-        command.Options.Add(OptionDefinitions.Common.ResourceGroup.AsRequired());
-        command.Options.Add(AppLensOptionDefinitions.Question);
-        command.Options.Add(AppLensOptionDefinitions.Resource);
+        command.Options.Add(AppLensOptionDefinitions.Subscription);
+        command.Options.Add(AppLensOptionDefinitions.ResourceGroup);
         command.Options.Add(AppLensOptionDefinitions.ResourceType);
+        command.Options.Add(AppLensOptionDefinitions.Resource);
+        command.Options.Add(AppLensOptionDefinitions.Question);
     }
 
     protected override ResourceDiagnoseOptions BindOptions(ParseResult parseResult)
     {
         var options = base.BindOptions(parseResult);
-        options.ResourceGroup ??= parseResult.GetValueOrDefault<string>(OptionDefinitions.Common.ResourceGroup.Name);
+        options.Subscription = parseResult.GetValueOrDefault<string>(AppLensOptionDefinitions.Subscription.Name);
+        options.ResourceGroup = parseResult.GetValueOrDefault<string>(AppLensOptionDefinitions.ResourceGroup.Name);
         options.Question = parseResult.GetValueOrDefault<string>(AppLensOptionDefinitions.Question.Name) ?? string.Empty;
         options.Resource = parseResult.GetValueOrDefault<string>(AppLensOptionDefinitions.Resource.Name) ?? string.Empty;
-        options.ResourceType ??= parseResult.GetValueOrDefault<string>(AppLensOptionDefinitions.ResourceType.Name);
+        options.ResourceType = parseResult.GetValueOrDefault<string>(AppLensOptionDefinitions.ResourceType.Name);
         return options;
     }
 
@@ -80,7 +83,7 @@ public override async Task<CommandResponse> ExecuteAsync(CommandContext context,
             var result = await _appLensService.DiagnoseResourceAsync(
                 options.Question,
                 options.Resource,
-                options.Subscription!,
+                options.Subscription,
                 options.ResourceGroup,
                 options.ResourceType,
                 options.Tenant,

tools/Azure.Mcp.Tools.AppLens/src/Options/AppLensOptionDefinitions.cs

@@ -8,6 +8,8 @@ public static class AppLensOptionDefinitions
     public const string QuestionName = "question";
     public const string ResourceName = "resource";
     public const string ResourceTypeName = "resource-type";
+    public const string ResourceGroupName = "resource-group";
+    public const string SubscriptionName = "subscription";
 
     public static readonly Option<string> Question = new(
         $"--{QuestionName}")
@@ -23,10 +25,24 @@ public static class AppLensOptionDefinitions
         Required = true
     };
 
+    public static readonly Option<string?> Subscription = new(
+        $"--{SubscriptionName}")
+    {
+        Description = "Azure subscription ID or name. Provide this when disambiguating between multiple resources of the same name.",
+        Required = false
+    };
+
+    public static readonly Option<string?> ResourceGroup = new(
+        $"--{ResourceGroupName}")
+    {
+        Description = "Azure resource group name. Provide this when disambiguating between multiple resources of the same name.",
+        Required = false
+    };
+
     public static readonly Option<string?> ResourceType = new(
         $"--{ResourceTypeName}")
     {
-        Description = "Resource type. Try to get this information using the Azure CLI tool before asking the user.",
-        Required = true
+        Description = "Resource type. Provide this when disambiguating between multiple resources of the same name.",
+        Required = false
     };
 }

tools/Azure.Mcp.Tools.AppLens/src/Options/Resource/ResourceDiagnoseOptions.cs

@@ -8,7 +8,7 @@ namespace Azure.Mcp.Tools.AppLens.Options.Resource;
 /// <summary>
 /// Options for the AppLens resource diagnose command.
 /// </summary>
-public class ResourceDiagnoseOptions : SubscriptionOptions
+public class ResourceDiagnoseOptions : GlobalOptions
 {
     /// <summary>
     /// The user's question for diagnosis.
@@ -21,7 +21,12 @@ public class ResourceDiagnoseOptions : SubscriptionOptions
     public string Resource { get; set; } = string.Empty;
 
     /// <summary>
-    /// The Resource Type of the resource to diagnose
+    /// The Resource Type of the resource to diagnose. This is optional and used to disambiguate between multiple resources with the same name.
     /// </summary>
     public string? ResourceType { get; set; }
+
+    /// <summary>
+    /// The subscription of the resource to diagnose. This is optional and used to disambiguate between multiple resources with the same name.
+    /// </summary>
+    public string? Subscription { get; set; }
 }