Tool search configuration support (#1933)

* Tool search configuration support

* Fix ResumeSessionConfig

* Fix spotless check

* Fix Copilot comments

* Fetch available tools for tool search

* Addressing CI and alerts

* Addressing review comments

* Fix formatting

* Fix spotless check

Author: almaleksia

dotnet/src/Client.cs

@@ -1137,6 +1137,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
                 InstructionDirectories: config.InstructionDirectories,
                 PluginDirectories: config.PluginDirectories,
                 LargeOutput: config.LargeOutput,
+                ToolSearch: config.ToolSearch,
                 Memory: config.Memory,
                 Canvases: config.Canvases,
                 RequestCanvasRenderer: config.RequestCanvasRenderer,
@@ -1348,6 +1349,7 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
                 InstructionDirectories: config.InstructionDirectories,
                 PluginDirectories: config.PluginDirectories,
                 LargeOutput: config.LargeOutput,
+                ToolSearch: config.ToolSearch,
                 Memory: config.Memory,
                 Canvases: config.Canvases,
                 RequestCanvasRenderer: config.RequestCanvasRenderer,
@@ -2689,6 +2691,7 @@ internal record CreateSessionRequest(
         IList<string>? InstructionDirectories = null,
         IList<string>? PluginDirectories = null,
         LargeToolOutputConfig? LargeOutput = null,
+        ToolSearchConfig? ToolSearch = null,
         MemoryConfiguration? Memory = null,
 #pragma warning disable GHCP001
         IList<CanvasDeclaration>? Canvases = null,
@@ -2790,6 +2793,7 @@ internal record ResumeSessionRequest(
         IList<string>? InstructionDirectories = null,
         IList<string>? PluginDirectories = null,
         LargeToolOutputConfig? LargeOutput = null,
+        ToolSearchConfig? ToolSearch = null,
         MemoryConfiguration? Memory = null,
 #pragma warning disable GHCP001
         IList<CanvasDeclaration>? Canvases = null,

dotnet/src/Session.cs

@@ -90,6 +90,13 @@ private sealed record EventSubscription(Type EventType, Action<SessionEvent> Han
     private readonly Channel<SessionEvent> _eventChannel = Channel.CreateUnbounded<SessionEvent>(
         new() { SingleReader = true });
 
+    /// <summary>
+    /// Fixed name of the runtime's built-in tool-search tool. A client can
+    /// replace its behavior by registering a tool with this exact name and
+    /// <c>OverridesBuiltInTool</c> set to <c>true</c>.
+    /// </summary>
+    private const string ToolSearchToolName = "tool_search_tool";
+
     /// <summary>
     /// Gets the unique identifier for this session.
     /// </summary>
@@ -841,6 +848,26 @@ private async Task ExecuteToolAndRespondAsync(string requestId, string toolName,
                 Arguments = arguments
             };
 
+            // The built-in tool-search tool receives a snapshot of the session's
+            // currently initialized tools so an override can filter the live
+            // catalog without issuing its own RPC. Fetch it only for that tool
+            // to avoid a round-trip on every tool call; a failed fetch leaves
+            // the snapshot null rather than failing the tool.
+            if (toolName == ToolSearchToolName)
+            {
+                try
+                {
+                    var metadata = await Rpc.Tools.GetCurrentMetadataAsync();
+                    invocation.AvailableTools = metadata.Tools;
+                }
+                catch (Exception ex) when (ex is RemoteRpcException or IOException or ObjectDisposedException or JsonException)
+                {
+                    // A failed metadata fetch is non-fatal: leave AvailableTools
+                    // null so the tool still runs without the snapshot.
+                    LogToolMetadataFetchFailed(ex, toolName);
+                }
+            }
+
             var aiFunctionArgs = new AIFunctionArguments
             {
                 Context = new Dictionary<object, object?>
@@ -1907,6 +1934,9 @@ await InvokeRpcAsync<object>(
     [LoggerMessage(Level = LogLevel.Error, Message = "Unhandled exception in session event handler")]
     private partial void LogEventHandlerError(Exception exception);
 
+    [LoggerMessage(Level = LogLevel.Debug, Message = "Failed to fetch tool metadata for {toolName}")]
+    private partial void LogToolMetadataFetchFailed(Exception exception, string toolName);
+
     internal record SendMessageRequest
     {
         public string SessionId { get; init; } = string.Empty;

dotnet/src/Types.cs

@@ -697,6 +697,12 @@ public sealed class ToolResultObject
     [JsonPropertyName("toolTelemetry")]
     public IDictionary<string, object>? ToolTelemetry { get; set; }
 
+    /// <summary>
+    /// Names of tools returned by a tool-search tool.
+    /// </summary>
+    [JsonPropertyName("toolReferences")]
+    public IList<string>? ToolReferences { get; set; }
+
     /// <summary>
     /// Converts the result of an <see cref="AIFunction"/> invocation into a
     /// <see cref="ToolResultObject"/>. Handles <see cref="ToolResultAIContent"/>,
@@ -808,6 +814,14 @@ public sealed class ToolInvocation
     /// Arguments passed to the tool by the language model.
     /// </summary>
     public JsonElement? Arguments { get; set; }
+    /// <summary>
+    /// Snapshot of the session's currently initialized tools. The SDK populates
+    /// this only when the invocation targets the built-in tool-search tool
+    /// (<c>tool_search_tool</c>), so a tool-search override can rank/filter the
+    /// live catalog — including MCP tools configured in settings — without
+    /// issuing its own RPC. <c>null</c> for every other tool invocation.
+    /// </summary>
+    public IList<CurrentToolMetadata>? AvailableTools { get; set; }
 }
 
 /// <summary>
@@ -2721,6 +2735,30 @@ public sealed class LargeToolOutputConfig
     public string? OutputDirectory { get; set; }
 }
 
+/// <summary>
+/// Overrides the runtime's built-in tool-search behavior.
+/// Defers tools to keep the model's active tool set small.
+/// To override the tool-search tool's implementation, register a tool
+/// named "tool_search_tool" with <c>OverridesBuiltInTool</c> set to
+/// <see langword="true"/>.
+/// </summary>
+public sealed class ToolSearchConfig
+{
+    /// <summary>
+    /// Enable or disable tool search.
+    /// </summary>
+    [JsonPropertyName("enabled")]
+    public bool? Enabled { get; set; }
+
+    /// <summary>
+    /// The tool count above which MCP and external tools are deferred behind
+    /// tool search. When <see langword="null"/>, the runtime default (30)
+    /// applies.
+    /// </summary>
+    [JsonPropertyName("deferThreshold")]
+    public int? DeferThreshold { get; set; }
+}
+
 /// <summary>
 /// Configuration for session memory.
 /// </summary>
@@ -2829,6 +2867,7 @@ protected SessionConfigBase(SessionConfigBase? other)
         Hooks = other.Hooks;
         InfiniteSessions = other.InfiniteSessions;
         LargeOutput = other.LargeOutput;
+        ToolSearch = other.ToolSearch;
         Memory = other.Memory;
         McpServers = other.McpServers is not null
             ? (other.McpServers is Dictionary<string, McpServerConfig> dict
@@ -3235,6 +3274,13 @@ protected SessionConfigBase(SessionConfigBase? other)
     /// </summary>
     public LargeToolOutputConfig? LargeOutput { get; set; }
 
+    /// <summary>
+    /// Overrides the runtime's built-in tool-search behavior.
+    /// Tool search defers tools to keep the model's active tool set small. When <see langword="null"/>,
+    /// the runtime default applies.
+    /// </summary>
+    public ToolSearchConfig? ToolSearch { get; set; }
+
     /// <summary>
     /// Configuration for session memory. When set, controls whether the
     /// session can read and write persistent memory.

dotnet/test/Unit/SerializationTests.cs

@@ -856,6 +856,48 @@ public void HooksInvokeResponse_SerializesNullOutput_AsEmptyOrNoOutputProperty()
         // else: property omitted, which is fine (runtime treats undefined output as no-op)
     }
 
+    [Fact]
+    public void ToolResultObject_SerializesToolReferences_WithSdkOptions()
+    {
+        var options = GetSerializerOptions();
+        var original = new ToolResultObject
+        {
+            TextResultForLlm = "found 2 tools",
+            ResultType = "success",
+            ToolReferences = ["get_weather", "check_status"],
+        };
+
+        var json = JsonSerializer.Serialize(original, options);
+        using var document = JsonDocument.Parse(json);
+        var root = document.RootElement;
+        Assert.Equal("found 2 tools", root.GetProperty("textResultForLlm").GetString());
+        var refs = root.GetProperty("toolReferences");
+        Assert.Equal(JsonValueKind.Array, refs.ValueKind);
+        Assert.Equal(2, refs.GetArrayLength());
+        Assert.Equal("get_weather", refs[0].GetString());
+        Assert.Equal("check_status", refs[1].GetString());
+
+        var deserialized = JsonSerializer.Deserialize<ToolResultObject>(json, options);
+        Assert.NotNull(deserialized);
+        string[] expectedReferences = ["get_weather", "check_status"];
+        Assert.Equal(expectedReferences, deserialized!.ToolReferences);
+    }
+
+    [Fact]
+    public void ToolResultObject_OmitsToolReferences_WhenNull_WithSdkOptions()
+    {
+        var options = GetSerializerOptions();
+        var original = new ToolResultObject
+        {
+            TextResultForLlm = "ok",
+            ResultType = "success",
+        };
+
+        var json = JsonSerializer.Serialize(original, options);
+        using var document = JsonDocument.Parse(json);
+        Assert.False(document.RootElement.TryGetProperty("toolReferences", out _));
+    }
+
     private static JsonSerializerOptions GetSerializerOptions()
     {
         var prop = typeof(CopilotClient)

go/client.go

@@ -722,6 +722,7 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 	req.DisabledSkills = config.DisabledSkills
 	req.InfiniteSessions = config.InfiniteSessions
 	req.LargeOutput = config.LargeOutput
+	req.ToolSearch = config.ToolSearch
 	req.Memory = config.Memory
 	req.GitHubToken = config.GitHubToken
 	req.RemoteSession = config.RemoteSession
@@ -1088,6 +1089,7 @@ func (c *Client) ResumeSessionWithOptions(ctx context.Context, sessionID string,
 	req.DisabledSkills = config.DisabledSkills
 	req.InfiniteSessions = config.InfiniteSessions
 	req.LargeOutput = config.LargeOutput
+	req.ToolSearch = config.ToolSearch
 	req.Memory = config.Memory
 	req.GitHubToken = config.GitHubToken
 	req.RemoteSession = config.RemoteSession

go/session.go

@@ -13,6 +13,11 @@ import (
 	"github.com/github/copilot-sdk/go/rpc"
 )
 
+// toolSearchToolName is the fixed name of the runtime's built-in tool-search
+// tool. A client can replace its behavior by registering a [Tool] with this
+// exact name and OverridesBuiltInTool set to true.
+const toolSearchToolName = "tool_search_tool"
+
 type sessionHandler struct {
 	id uint64
 	fn SessionEventHandler
@@ -1513,6 +1518,17 @@ func (s *Session) executeToolAndRespond(requestID, toolName, toolCallID string,
 		TraceContext: ctx,
 	}
 
+	// The built-in tool-search tool receives a snapshot of the session's
+	// currently initialized tools so an override can filter the live catalog
+	// without issuing its own RPC. Fetch it only for that tool to avoid a
+	// round-trip on every tool call; a failed fetch leaves the snapshot nil
+	// rather than failing the tool.
+	if toolName == toolSearchToolName {
+		if metadata, mErr := s.RPC.Tools.GetCurrentMetadata(ctx); mErr == nil && metadata != nil {
+			invocation.AvailableTools = metadata.Tools
+		}
+	}
+
 	result, err := handler(invocation)
 	if err != nil {
 		errMsg := err.Error()
@@ -1542,6 +1558,7 @@ func (s *Session) executeToolAndRespond(requestID, toolName, toolCallID string,
 		TextResultForLlm: textResultForLLM,
 		ToolTelemetry:    result.ToolTelemetry,
 		ResultType:       &effectiveResultType,
+		ToolReferences:   result.ToolReferences,
 	}
 	if result.Error != "" {
 		rpcResult.Error = &result.Error

go/types.go

@@ -948,6 +948,18 @@ type LargeToolOutputConfig struct {
 	OutputDirectory string `json:"outputDir,omitempty"`
 }
 
+// ToolSearchConfig allows to configure tool search behavior.
+// Tool search defers tools to keep the model's active tool set small.
+// To override the tool-search tool's implementation, register a
+// [Tool] named "tool_search_tool" with OverridesBuiltInTool set to true.
+type ToolSearchConfig struct {
+	// Controls whether tool search is enabled.
+	Enabled *bool `json:"enabled,omitempty"`
+	// DeferThreshold is the tool count above which MCP and external tools are
+	// deferred behind tool search. When nil, the runtime default (30) applies.
+	DeferThreshold *int `json:"deferThreshold,omitempty"`
+}
+
 // SessionFSCapabilities declares optional provider capabilities.
 type SessionFSCapabilities struct {
 	// Sqlite indicates whether the provider supports SQLite query/exists operations.
@@ -1153,6 +1165,10 @@ type SessionConfig struct {
 	// output exceeding the configured size, the output is written to a temp file
 	// and a reference is returned to the model instead of the full payload.
 	LargeOutput *LargeToolOutputConfig
+	// ToolSearch overrides the runtime's built-in tool-search behavior, which
+	// defers rarely used tools behind a searchable index. When nil, the runtime
+	// default applies.
+	ToolSearch *ToolSearchConfig
 	// Memory configures the memory feature for the session. When omitted, the
 	// runtime default applies.
 	Memory *MemoryConfiguration
@@ -1290,6 +1306,14 @@ type ToolInvocation struct {
 	ToolName   string
 	Arguments  any
 
+	// AvailableTools is a snapshot of the session's currently initialized
+	// tools. The SDK populates it only when this invocation targets the
+	// built-in tool-search tool ("tool_search_tool"), so a tool-search
+	// override can rank/filter the live catalog -- including MCP tools
+	// configured in settings -- without issuing its own RPC. It is nil for
+	// every other tool invocation.
+	AvailableTools []rpc.CurrentToolMetadata
+
 	// TraceContext carries the W3C Trace Context propagated from the CLI's
 	// execute_tool span.  Pass this to OpenTelemetry-aware code so that
 	// child spans created inside the handler are parented to the CLI span.
@@ -1309,6 +1333,8 @@ type ToolResult struct {
 	Error               string             `json:"error,omitempty"`
 	SessionLog          string             `json:"sessionLog,omitempty"`
 	ToolTelemetry       map[string]any     `json:"toolTelemetry,omitempty"`
+	// ToolReferences lists names of tools returned by a tool-search tool.
+	ToolReferences []string `json:"toolReferences,omitempty"`
 }
 
 // CommandContext provides context about a slash-command invocation.
@@ -1605,6 +1631,10 @@ type ResumeSessionConfig struct {
 	// output exceeding the configured size, the output is written to a temp file
 	// and a reference is returned to the model instead of the full payload.
 	LargeOutput *LargeToolOutputConfig
+	// ToolSearch overrides the runtime's built-in tool-search behavior, which
+	// defers rarely used tools behind a searchable index. When nil, the runtime
+	// default applies.
+	ToolSearch *ToolSearchConfig
 	// Memory configures the memory feature for the session. When omitted, the
 	// runtime default applies.
 	Memory *MemoryConfiguration
@@ -2125,6 +2155,7 @@ type createSessionRequest struct {
 	DisabledSkills                     []string                               `json:"disabledSkills,omitempty"`
 	InfiniteSessions                   *InfiniteSessionConfig                 `json:"infiniteSessions,omitempty"`
 	LargeOutput                        *LargeToolOutputConfig                 `json:"largeOutput,omitempty"`
+	ToolSearch                         *ToolSearchConfig                      `json:"toolSearch,omitempty"`
 	Memory                             *MemoryConfiguration                   `json:"memory,omitempty"`
 	Commands                           []wireCommand                          `json:"commands,omitempty"`
 	RequestElicitation                 *bool                                  `json:"requestElicitation,omitempty"`
@@ -2216,6 +2247,7 @@ type resumeSessionRequest struct {
 	DisabledSkills                     []string                               `json:"disabledSkills,omitempty"`
 	InfiniteSessions                   *InfiniteSessionConfig                 `json:"infiniteSessions,omitempty"`
 	LargeOutput                        *LargeToolOutputConfig                 `json:"largeOutput,omitempty"`
+	ToolSearch                         *ToolSearchConfig                      `json:"toolSearch,omitempty"`
 	Memory                             *MemoryConfiguration                   `json:"memory,omitempty"`
 	Commands                           []wireCommand                          `json:"commands,omitempty"`
 	RequestElicitation                 *bool                                  `json:"requestElicitation,omitempty"`