Address PR feedback on auto-discovery APIs

Author: KSemenenko

README.md

@@ -278,7 +278,7 @@ using Microsoft.Extensions.DependencyInjection;
 await using var serviceProvider = services.BuildServiceProvider();
 
 var innerChatClient = serviceProvider.GetRequiredService<IChatClient>();
-using var chatClient = innerChatClient.UseManagedCodeMcpGatewayAutoDiscovery(
+using var chatClient = innerChatClient.UseMcpGatewayAutoDiscovery(
     serviceProvider,
     options =>
     {
@@ -321,7 +321,7 @@ await using var serviceProvider = services.BuildServiceProvider();
 
 var innerChatClient = serviceProvider.GetRequiredService<IChatClient>();
 var loggerFactory = serviceProvider.GetRequiredService<ILoggerFactory>();
-using var chatClient = innerChatClient.UseManagedCodeMcpGatewayAutoDiscovery(
+using var chatClient = innerChatClient.UseMcpGatewayAutoDiscovery(
     serviceProvider,
     options =>
     {

docs/ADR/ADR-0003-reusable-chat-client-and-agent-tool-modules.md

@@ -26,7 +26,7 @@ At the same time, the repository still wants to keep the core package generic, l
 - `McpGatewayToolSet.AddTools(...)` composes those tools into an existing `IList<AITool>` without duplicating names
 - `ChatOptions.AddMcpGatewayTools(...)` attaches the same tools to chat-client requests
 - `McpGatewayToolSet.CreateDiscoveredTools(...)` projects the latest search matches as direct proxy tools
-- `McpGatewayAutoDiscoveryChatClient` and `UseManagedCodeMcpGatewayAutoDiscovery(...)` provide the recommended staged host wrapper for both plain `IChatClient` and Agent Framework hosts
+- `McpGatewayAutoDiscoveryChatClient` and `UseMcpGatewayAutoDiscovery(...)` provide the recommended staged host wrapper for both plain `IChatClient` and Agent Framework hosts
 
 The recommended host flow is:
 
@@ -127,7 +127,7 @@ Mitigations:
 Rollout:
 
 1. Keep `McpGatewayToolSet` as the reusable module entry point.
-2. Add `McpGatewayAutoDiscoveryChatClient` and `UseManagedCodeMcpGatewayAutoDiscovery(...)` as the recommended host wrapper.
+2. Add `McpGatewayAutoDiscoveryChatClient` and `UseMcpGatewayAutoDiscovery(...)` as the recommended host wrapper.
 3. Document both chat-client and agent composition examples in `README.md`.
 4. Keep architecture docs aligned with the generic `AITool`-module approach.
 

docs/Architecture/Overview.md

@@ -26,7 +26,7 @@ Out of scope:
 
 `McpGateway` stays a thin facade over `McpGatewayRuntime`, which reads immutable catalog snapshots, coordinates vector or tokenizer-backed search, optionally rewrites queries through a keyed `IChatClient`, and invokes local or MCP tools. Optional startup warmup is available through a service-provider extension or hosted background service without changing the lazy default.
 
-The package also keeps chat-client and agent integration generic: `McpGatewayToolSet` is the source of reusable `AITool` meta-tools and discovered proxy tools, `ChatOptions.AddMcpGatewayTools(...)` remains the low-level bridge, and `McpGatewayAutoDiscoveryChatClient` plus `UseManagedCodeMcpGatewayAutoDiscovery(...)` provide the recommended staged host wrapper that starts with two meta-tools and replaces the discovered proxy set on each new search result without introducing a hard Agent Framework dependency into the core package.
+The package also keeps chat-client and agent integration generic: `McpGatewayToolSet` is the source of reusable `AITool` meta-tools and discovered proxy tools, `ChatOptions.AddMcpGatewayTools(...)` remains the low-level bridge, and `McpGatewayAutoDiscoveryChatClient` plus `UseMcpGatewayAutoDiscovery(...)` provide the recommended staged host wrapper that starts with two meta-tools and replaces the discovered proxy set on each new search result without introducing a hard Agent Framework dependency into the core package.
 
 ## System And Module Map
 
@@ -63,7 +63,7 @@ flowchart LR
     ToolSet --> ToolList["IList<AITool> composition"]
     ToolSet --> DiscoveredTools["CreateDiscoveredTools(...)"]
     ChatOptions["ChatOptions.AddMcpGatewayTools(...)"] --> ToolSet
-    AutoDiscovery["McpGatewayAutoDiscoveryChatClient / UseManagedCodeMcpGatewayAutoDiscovery(...)"] --> ToolSet
+    AutoDiscovery["McpGatewayAutoDiscoveryChatClient / UseMcpGatewayAutoDiscovery(...)"] --> ToolSet
     AutoDiscovery --> ChatClient
     Warmup["McpGatewayServiceProviderExtensions / McpGatewayIndexWarmupService"] --> IMcpGateway
     McpGateway --> Runtime["McpGatewayRuntime"]

src/ManagedCode.MCPGateway/McpGatewayAutoDiscoveryChatClient.cs

@@ -230,12 +230,19 @@ when functionNamesByCallId.TryGetValue(functionResult.CallId, out var functionNa
             }
 
             var serialized = McpGatewayJsonSerializer.TrySerializeToElement(result);
-            if (serialized is not JsonElement jsonElement)
+            if (serialized is not JsonElement { ValueKind: JsonValueKind.Object } jsonElement)
             {
                 return null;
             }
 
-            return jsonElement.Deserialize<McpGatewaySearchResult>(McpGatewayJsonSerializer.Options);
+            try
+            {
+                return jsonElement.Deserialize<McpGatewaySearchResult>(McpGatewayJsonSerializer.Options);
+            }
+            catch (JsonException)
+            {
+                return null;
+            }
         }
     }
 

src/ManagedCode.MCPGateway/McpGatewayToolSet.cs

@@ -50,7 +50,7 @@ public IList<AITool> AddTools(
     {
         ArgumentNullException.ThrowIfNull(tools);
 
-        var targetTools = tools.IsReadOnly ? new List<AITool>(tools) : tools;
+        var targetTools = new List<AITool>(tools);
         var toolNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
 
         foreach (var tool in targetTools)
@@ -249,6 +249,16 @@ private static string SanitizeToolName(string value)
             builder.Append(char.IsLetterOrDigit(character) || character == '_' ? character : '_');
         }
 
+        if (builder.Length == 0)
+        {
+            return "gateway_tool";
+        }
+
+        if (!char.IsLetter(builder[0]) && builder[0] != '_')
+        {
+            builder.Insert(0, "t_");
+        }
+
         return builder.ToString();
     }
 }

src/ManagedCode.MCPGateway/Registration/McpGatewayChatClientExtensions.cs

@@ -6,7 +6,7 @@ namespace ManagedCode.MCPGateway;
 
 public static class McpGatewayChatClientExtensions
 {
-    public static IChatClient UseManagedCodeMcpGatewayAutoDiscovery(
+    public static IChatClient UseMcpGatewayAutoDiscovery(
         this IChatClient chatClient,
         McpGatewayToolSet toolSet,
         ILoggerFactory? loggerFactory = null,
@@ -24,7 +24,7 @@ public static IChatClient UseManagedCodeMcpGatewayAutoDiscovery(
             options);
     }
 
-    public static IChatClient UseManagedCodeMcpGatewayAutoDiscovery(
+    public static IChatClient UseMcpGatewayAutoDiscovery(
         this IChatClient chatClient,
         IServiceProvider serviceProvider,
         Action<McpGatewayAutoDiscoveryOptions>? configure = null)
@@ -35,7 +35,7 @@ public static IChatClient UseManagedCodeMcpGatewayAutoDiscovery(
         var options = new McpGatewayAutoDiscoveryOptions();
         configure?.Invoke(options);
 
-        return chatClient.UseManagedCodeMcpGatewayAutoDiscovery(
+        return chatClient.UseMcpGatewayAutoDiscovery(
             serviceProvider.GetRequiredService<McpGatewayToolSet>(),
             serviceProvider.GetService<ILoggerFactory>(),
             serviceProvider,

src/ManagedCode.MCPGateway/Registration/McpGatewayChatOptionsExtensions.cs

@@ -32,20 +32,4 @@ public static ChatOptions AddMcpGatewayTools(
             searchToolName,
             invokeToolName);
     }
-
-    [Obsolete("Use AddMcpGatewayTools(...) instead.")]
-    public static ChatOptions AddManagedCodeMcpGatewayTools(
-        this ChatOptions options,
-        McpGatewayToolSet toolSet,
-        string searchToolName = McpGatewayToolSet.DefaultSearchToolName,
-        string invokeToolName = McpGatewayToolSet.DefaultInvokeToolName)
-        => options.AddMcpGatewayTools(toolSet, searchToolName, invokeToolName);
-
-    [Obsolete("Use AddMcpGatewayTools(...) instead.")]
-    public static ChatOptions AddManagedCodeMcpGatewayTools(
-        this ChatOptions options,
-        IServiceProvider serviceProvider,
-        string searchToolName = McpGatewayToolSet.DefaultSearchToolName,
-        string invokeToolName = McpGatewayToolSet.DefaultInvokeToolName)
-        => options.AddMcpGatewayTools(serviceProvider, searchToolName, invokeToolName);
 }

tests/ManagedCode.MCPGateway.Tests/Agents/McpGatewayAgentFrameworkIntegrationTests.cs

@@ -22,7 +22,7 @@ public async Task ChatClientAgent_UsesAutoDiscoveryWithoutEmbeddings()
         {
             Scenarios = GatewayIntegrationTestSupport.CreateAutoDiscoveryScenarios(useSemanticQueries: false)
         });
-        using var autoDiscoveryClient = modelClient.UseManagedCodeMcpGatewayAutoDiscovery(
+        using var autoDiscoveryClient = modelClient.UseMcpGatewayAutoDiscovery(
             serviceProvider,
             options => options.MaxDiscoveredTools = 2);
 
@@ -67,7 +67,7 @@ public async Task ChatClientAgent_UsesAutoDiscoveryWithEmbeddings()
         {
             Scenarios = GatewayIntegrationTestSupport.CreateAutoDiscoveryScenarios(useSemanticQueries: true)
         });
-        using var autoDiscoveryClient = modelClient.UseManagedCodeMcpGatewayAutoDiscovery(
+        using var autoDiscoveryClient = modelClient.UseMcpGatewayAutoDiscovery(
             serviceProvider,
             options => options.MaxDiscoveredTools = 2);
 

tests/ManagedCode.MCPGateway.Tests/ChatClient/McpGatewayChatClientIntegrationTests.cs

@@ -2,6 +2,7 @@
 
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.DependencyInjection;
+using System.Text.Json;
 
 namespace ManagedCode.MCPGateway.Tests;
 
@@ -25,6 +26,59 @@ await Assert.That(options.Tools.Select(static tool => tool.Name)).IsEquivalentTo
             ]);
     }
 
+    [TUnit.Core.Test]
+    public async Task ToolSet_AddTools_ReturnsNewListWithoutMutatingInput()
+    {
+        await using var serviceProvider = GatewayTestServiceProviderFactory.Create(static _ => { });
+        var toolSet = serviceProvider.GetRequiredService<McpGatewayToolSet>();
+        var existingTools = new List<AITool>
+        {
+            TestFunctionFactory.CreateFunction(
+                static () => "existing",
+                "existing_tool",
+                "Existing tool.")
+        };
+
+        var composedTools = toolSet.AddTools(existingTools);
+
+        await Assert.That(existingTools.Count).IsEqualTo(1);
+        await Assert.That(composedTools.Count).IsEqualTo(3);
+        await Assert.That(ReferenceEquals(existingTools, composedTools)).IsFalse();
+    }
+
+    [TUnit.Core.Test]
+    public async Task AutoDiscoveryChatClient_IgnoresPrimitiveSearchResultPayloads()
+    {
+        await using var serviceProvider = GatewayTestServiceProviderFactory.Create(static _ => { });
+        var modelClient = new TestChatClient(new TestChatClientOptions
+        {
+            Scenarios =
+            [
+                new TestChatClientScenario(
+                    "return text",
+                    static _ => true,
+                    static _ => TestChatClientScenario.Text("ok"))
+            ]
+        });
+
+        using var chatClient = modelClient.UseMcpGatewayAutoDiscovery(serviceProvider);
+
+        var response = await chatClient.GetResponseAsync(
+        [
+            new ChatMessage(ChatRole.User, "Find the right tools."),
+            new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("search-1", McpGatewayToolSet.DefaultSearchToolName, new Dictionary<string, object?>())]),
+            new ChatMessage(ChatRole.Assistant, [new FunctionResultContent("search-1", JsonSerializer.SerializeToElement("not-an-object"))])
+        ]);
+
+        await Assert.That(response.Text).IsEqualTo("ok");
+        await Assert.That(modelClient.Invocations.Count).IsEqualTo(1);
+        await Assert.That(modelClient.Invocations[0].ToolNames).IsEquivalentTo(
+            [
+                McpGatewayToolSet.DefaultSearchToolName,
+                McpGatewayToolSet.DefaultInvokeToolName
+            ]);
+    }
+
     [TUnit.Core.Test]
     public async Task AutoDiscoveryChatClient_ReplacesDiscoveredToolsWithoutEmbeddings()
     {
@@ -38,7 +92,7 @@ public async Task AutoDiscoveryChatClient_ReplacesDiscoveredToolsWithoutEmbeddin
             Scenarios = GatewayIntegrationTestSupport.CreateAutoDiscoveryScenarios(useSemanticQueries: false)
         });
 
-        using var chatClient = modelClient.UseManagedCodeMcpGatewayAutoDiscovery(
+        using var chatClient = modelClient.UseMcpGatewayAutoDiscovery(
             serviceProvider,
             options => options.MaxDiscoveredTools = 2);
 
@@ -72,7 +126,7 @@ public async Task AutoDiscoveryChatClient_ReplacesDiscoveredToolsWithEmbeddings(
             Scenarios = GatewayIntegrationTestSupport.CreateAutoDiscoveryScenarios(useSemanticQueries: true)
         });
 
-        using var chatClient = modelClient.UseManagedCodeMcpGatewayAutoDiscovery(
+        using var chatClient = modelClient.UseMcpGatewayAutoDiscovery(
             serviceProvider,
             options => options.MaxDiscoveredTools = 2);
 

tests/ManagedCode.MCPGateway.Tests/MetaTools/McpGatewayMetaToolTests.cs

@@ -69,6 +69,30 @@ public async Task CreateMetaTools_InvokeToolSupportsContextSummary()
         await Assert.That(GetJsonProperty(invokeResult, "output").GetString()).IsEqualTo("open github|user is on repository settings page");
     }
 
+    [TUnit.Core.Test]
+    public async Task CreateDiscoveredTools_PrefixesNamesThatStartWithDigits()
+    {
+        await using var serviceProvider = GatewayTestServiceProviderFactory.Create(static _ => { });
+        var toolSet = serviceProvider.GetRequiredService<McpGatewayToolSet>();
+
+        var discoveredTools = toolSet.CreateDiscoveredTools(
+        [
+            new McpGatewaySearchMatch(
+                ToolId: "local:123-tool",
+                SourceId: "9-source",
+                SourceKind: McpGatewaySourceKind.Local,
+                ToolName: "123 tool",
+                DisplayName: null,
+                Description: "Example tool.",
+                RequiredArguments: [],
+                InputSchemaJson: null,
+                Score: 0.9d)
+        ]);
+
+        await Assert.That(discoveredTools.Count).IsEqualTo(1);
+        await Assert.That(discoveredTools[0].Name).IsEqualTo("t_123_tool");
+    }
+
     private static AIFunction GetFunction(IReadOnlyList<AITool> tools, string toolName)
         => (tools.Single(tool => tool.Name == toolName) as AIFunction)
            ?? throw new InvalidOperationException($"Tool '{toolName}' is not an AIFunction.");