rm ToolSearchEntry

codex-rs/app-server/README.md

@@ -1167,7 +1167,7 @@ If the session approval policy uses `Granular` with `request_permissions: false`
 
 `dynamicTools` on `thread/start` and the corresponding `item/tool/call` request/response flow are experimental APIs. To enable them, set `initialize.params.capabilities.experimentalApi = true`.
 
-Each dynamic tool may set `deferLoading`. When omitted, it defaults to `false`. Set it to `true` to keep the tool registered and callable by runtime features such as `js_repl`, while excluding it from the model-facing tool list sent on ordinary turns.
+Each dynamic tool may set `deferLoading`. When omitted, it defaults to `false`. Set it to `true` to keep the tool registered and callable by runtime features such as `js_repl`, while excluding it from the model-facing tool list sent on ordinary turns. When `tool_search` is available, deferred dynamic tools are searchable and can be exposed by a matching search result.
 
 When a dynamic tool is invoked during a turn, the server sends an `item/tool/call` JSON-RPC request to the client:
 

codex-rs/app-server/tests/suite/v2/dynamic_tools.rs

@@ -4,6 +4,7 @@ use app_test_support::McpProcess;
 use app_test_support::create_final_assistant_message_sse_response;
 use app_test_support::create_mock_responses_server_sequence_unchecked;
 use app_test_support::to_response;
+use app_test_support::write_models_cache_with_models;
 use codex_app_server_protocol::DynamicToolCallOutputContentItem;
 use codex_app_server_protocol::DynamicToolCallParams;
 use codex_app_server_protocol::DynamicToolCallResponse;
@@ -21,6 +22,7 @@ use codex_app_server_protocol::ThreadStartResponse;
 use codex_app_server_protocol::TurnStartParams;
 use codex_app_server_protocol::TurnStartResponse;
 use codex_app_server_protocol::UserInput as V2UserInput;
+use codex_models_manager::bundled_models_response;
 use codex_protocol::models::FunctionCallOutputBody;
 use codex_protocol::models::FunctionCallOutputContentItem;
 use codex_protocol::models::FunctionCallOutputPayload;
@@ -28,6 +30,7 @@ use core_test_support::responses;
 use pretty_assertions::assert_eq;
 use serde_json::Value;
 use serde_json::json;
+use std::io::Write;
 use std::path::Path;
 use std::time::Duration;
 use tempfile::TempDir;
@@ -196,6 +199,178 @@ async fn thread_start_keeps_hidden_dynamic_tools_out_of_model_requests() -> Resu
     Ok(())
 }
 
+/// Exercises deferred dynamic tool discovery, the follow-up tool call, and the tool response.
+#[tokio::test]
+async fn deferred_dynamic_tool_can_be_discovered_and_called_through_tool_search() -> Result<()> {
+    let search_call_id = "tool-search-1";
+    let dynamic_call_id = "dyn-search-call-1";
+    let tool_name = "automation_update";
+    let tool_description = "Create, update, view, or delete recurring automations.";
+    let tool_args = json!({ "mode": "create" });
+    let tool_call_arguments = serde_json::to_string(&tool_args)?;
+
+    let responses = vec![
+        responses::sse(vec![
+            responses::ev_response_created("resp-1"),
+            responses::ev_tool_search_call(
+                search_call_id,
+                &json!({
+                    "query": "recurring automations",
+                    "limit": 8,
+                }),
+            ),
+            responses::ev_completed("resp-1"),
+        ]),
+        responses::sse(vec![
+            responses::ev_response_created("resp-2"),
+            responses::ev_function_call(dynamic_call_id, tool_name, &tool_call_arguments),
+            responses::ev_completed("resp-2"),
+        ]),
+        create_final_assistant_message_sse_response("Done")?,
+    ];
+    let server = create_mock_responses_server_sequence_unchecked(responses).await;
+
+    let codex_home = TempDir::new()?;
+    write_search_capable_models_cache(codex_home.path())?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+    enable_tool_search_feature(codex_home.path())?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let input_schema = json!({
+        "type": "object",
+        "properties": {
+            "mode": { "type": "string" }
+        },
+        "required": ["mode"],
+        "additionalProperties": false,
+    });
+    let dynamic_tool = DynamicToolSpec {
+        name: tool_name.to_string(),
+        description: tool_description.to_string(),
+        input_schema: input_schema.clone(),
+        defer_loading: true,
+    };
+
+    let thread_req = mcp
+        .send_thread_start_request(ThreadStartParams {
+            dynamic_tools: Some(vec![dynamic_tool]),
+            ..Default::default()
+        })
+        .await?;
+    let thread_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(thread_req)),
+    )
+    .await??;
+    let ThreadStartResponse { thread, .. } = to_response::<ThreadStartResponse>(thread_resp)?;
+    let thread_id = thread.id.clone();
+
+    let turn_req = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: thread_id.clone(),
+            input: vec![V2UserInput::Text {
+                text: "Use the automation tool".to_string(),
+                text_elements: Vec::new(),
+            }],
+            ..Default::default()
+        })
+        .await?;
+    let turn_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(turn_req)),
+    )
+    .await??;
+    let TurnStartResponse { turn } = to_response::<TurnStartResponse>(turn_resp)?;
+    let turn_id = turn.id.clone();
+
+    let started = wait_for_dynamic_tool_started(&mut mcp, dynamic_call_id).await?;
+    assert_eq!(started.thread_id, thread_id.clone());
+    assert_eq!(started.turn_id, turn_id.clone());
+
+    let request = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_request_message(),
+    )
+    .await??;
+    let (request_id, params) = match request {
+        ServerRequest::DynamicToolCall { request_id, params } => (request_id, params),
+        other => panic!("expected DynamicToolCall request, got {other:?}"),
+    };
+    assert_eq!(
+        params,
+        DynamicToolCallParams {
+            thread_id: thread_id.clone(),
+            turn_id: turn_id.clone(),
+            call_id: dynamic_call_id.to_string(),
+            tool: tool_name.to_string(),
+            arguments: tool_args.clone(),
+        }
+    );
+
+    mcp.send_response(
+        request_id,
+        serde_json::to_value(DynamicToolCallResponse {
+            content_items: vec![DynamicToolCallOutputContentItem::InputText {
+                text: "dynamic-search-ok".to_string(),
+            }],
+            success: true,
+        })?,
+    )
+    .await?;
+
+    let completed = wait_for_dynamic_tool_completed(&mut mcp, dynamic_call_id).await?;
+    assert_eq!(completed.thread_id, thread_id);
+    assert_eq!(completed.turn_id, turn_id);
+
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let bodies = responses_bodies(&server).await?;
+    let first_request = bodies
+        .first()
+        .context("expected an initial responses request")?;
+    assert!(
+        find_tool_by_type(first_request, "tool_search").is_some(),
+        "initial request should advertise tool_search: {first_request:?}"
+    );
+    assert!(
+        find_tool(first_request, tool_name).is_none(),
+        "deferred dynamic tool should not be directly advertised before search"
+    );
+
+    let search_tools = bodies
+        .iter()
+        .find_map(|body| tool_search_output_tools(body, search_call_id))
+        .context("expected tool_search_output in follow-up request")?;
+    assert_eq!(
+        search_tools,
+        vec![json!({
+            "type": "function",
+            "name": tool_name,
+            "description": tool_description,
+            "strict": false,
+            "defer_loading": true,
+            "parameters": input_schema,
+        })]
+    );
+
+    let payload = bodies
+        .iter()
+        .find_map(|body| function_call_output_payload(body, dynamic_call_id))
+        .context("expected function_call_output in post-tool follow-up request")?;
+    assert_eq!(
+        payload,
+        FunctionCallOutputPayload::from_text("dynamic-search-ok".to_string())
+    );
+
+    Ok(())
+}
+
 /// Exercises the full dynamic tool call path (server request, client response, model output).
 #[tokio::test]
 async fn dynamic_tool_call_round_trip_sends_text_content_items_to_model() -> Result<()> {
@@ -583,6 +758,30 @@ fn find_tool<'a>(body: &'a Value, name: &str) -> Option<&'a Value> {
         })
 }
 
+fn find_tool_by_type<'a>(body: &'a Value, tool_type: &str) -> Option<&'a Value> {
+    body.get("tools")
+        .and_then(Value::as_array)
+        .and_then(|tools| {
+            tools
+                .iter()
+                .find(|tool| tool.get("type").and_then(Value::as_str) == Some(tool_type))
+        })
+}
+
+fn tool_search_output_tools(body: &Value, call_id: &str) -> Option<Vec<Value>> {
+    body.get("input")
+        .and_then(Value::as_array)
+        .and_then(|items| {
+            items.iter().find(|item| {
+                item.get("type").and_then(Value::as_str) == Some("tool_search_output")
+                    && item.get("call_id").and_then(Value::as_str) == Some(call_id)
+            })
+        })
+        .and_then(|item| item.get("tools"))
+        .and_then(Value::as_array)
+        .cloned()
+}
+
 fn function_call_output_payload(body: &Value, call_id: &str) -> Option<FunctionCallOutputPayload> {
     function_call_output_raw_output(body, call_id)
         .and_then(|output| serde_json::from_value(output).ok())
@@ -663,3 +862,24 @@ stream_max_retries = 0
         ),
     )
 }
+
+fn enable_tool_search_feature(codex_home: &Path) -> std::io::Result<()> {
+    let mut config_toml = std::fs::OpenOptions::new()
+        .append(true)
+        .open(codex_home.join("config.toml"))?;
+    config_toml.write_all(b"\n[features]\ntool_search = true\n")
+}
+
+fn write_search_capable_models_cache(codex_home: &Path) -> Result<()> {
+    let mut model = bundled_models_response()
+        .context("bundled models should parse")?
+        .models
+        .into_iter()
+        .find(|model| model.slug == "gpt-5.4")
+        .context("expected bundled gpt-5.4 model")?;
+    model.slug = "mock-model".to_string();
+    model.display_name = "mock-model".to_string();
+    model.supports_search_tool = true;
+    write_models_cache_with_models(codex_home, vec![model])?;
+    Ok(())
+}

codex-rs/core/src/tools/handlers/tool_search.rs

@@ -9,34 +9,48 @@ use bm25::Language;
 use bm25::SearchEngine;
 use bm25::SearchEngineBuilder;
 use codex_mcp::ToolInfo;
+use codex_protocol::dynamic_tools::DynamicToolSpec;
+use codex_tools::ResponsesApiNamespace;
+use codex_tools::ResponsesApiNamespaceTool;
 use codex_tools::TOOL_SEARCH_DEFAULT_LIMIT;
 use codex_tools::TOOL_SEARCH_TOOL_NAME;
-use codex_tools::ToolSearchResultSource;
-use codex_tools::collect_tool_search_output_tools;
+use codex_tools::ToolSearchOutputTool;
+use codex_tools::dynamic_tool_to_responses_api_tool;
+use codex_tools::mcp_tool_to_deferred_responses_api_tool;
 
 const COMPUTER_USE_MCP_SERVER_NAME: &str = "computer-use";
 const COMPUTER_USE_TOOL_SEARCH_LIMIT: usize = 20;
 
 pub struct ToolSearchHandler {
-    entries: Vec<(String, ToolInfo)>,
+    mcp_tools: Vec<ToolInfo>,
+    dynamic_tools: Vec<DynamicToolSpec>,
     search_engine: SearchEngine<usize>,
 }
 
 impl ToolSearchHandler {
-    pub fn new(tools: std::collections::HashMap<String, ToolInfo>) -> Self {
-        let mut entries: Vec<(String, ToolInfo)> = tools.into_iter().collect();
-        entries.sort_by(|a, b| a.0.cmp(&b.0));
+    pub fn new(
+        mcp_tools: std::collections::HashMap<String, ToolInfo>,
+        dynamic_tools: Vec<DynamicToolSpec>,
+    ) -> Self {
+        let mut mcp_tools: Vec<ToolInfo> = mcp_tools.into_values().collect();
+        mcp_tools.sort_by_key(|info| info.canonical_tool_name().display());
 
-        let documents: Vec<Document<usize>> = entries
+        let mut dynamic_tools = dynamic_tools;
+        dynamic_tools.sort_by(|a, b| a.name.cmp(&b.name));
+
+        let documents: Vec<Document<usize>> = mcp_tools
             .iter()
+            .map(build_mcp_search_text)
+            .chain(dynamic_tools.iter().map(build_dynamic_search_text))
             .enumerate()
-            .map(|(idx, (name, info))| Document::new(idx, build_search_text(name, info)))
+            .map(|(idx, search_text)| Document::new(idx, search_text))
             .collect();
         let search_engine =
             SearchEngineBuilder::<usize>::with_documents(Language::English, documents).build();
 
         Self {
-            entries,
+            mcp_tools,
+            dynamic_tools,
             search_engine,
         }
     }
@@ -79,77 +93,129 @@ impl ToolHandler for ToolSearchHandler {
             ));
         }
 
-        if self.entries.is_empty() {
+        if self.mcp_tools.is_empty() && self.dynamic_tools.is_empty() {
             return Ok(ToolSearchOutput { tools: Vec::new() });
         }
 
-        let results = self.search_result_entries(query, limit, requested_limit.is_none());
-
-        let tools = collect_tool_search_output_tools(results.into_iter().map(|(_, tool)| {
-            ToolSearchResultSource {
-                server_name: tool.server_name.as_str(),
-                tool_namespace: tool.callable_namespace.as_str(),
-                tool_name: tool.callable_name.as_str(),
-                tool: &tool.tool,
-                connector_name: tool.connector_name.as_deref(),
-                connector_description: tool.connector_description.as_deref(),
-            }
-        }))
-        .map_err(|err| {
-            FunctionCallError::Fatal(format!(
-                "failed to encode {TOOL_SEARCH_TOOL_NAME} output: {err}"
-            ))
-        })?;
+        let tools = self.search(query, limit, requested_limit.is_none())?;
 
         Ok(ToolSearchOutput { tools })
     }
 }
 
 impl ToolSearchHandler {
-    fn search_result_entries(
+    fn search(
         &self,
         query: &str,
         limit: usize,
         use_default_limit: bool,
-    ) -> Vec<&(String, ToolInfo)> {
+    ) -> Result<Vec<ToolSearchOutputTool>, FunctionCallError> {
+        let result_ids = self.search_result_ids(query, limit, use_default_limit);
+        self.search_output_tools(result_ids)
+    }
+
+    fn search_result_ids(&self, query: &str, limit: usize, use_default_limit: bool) -> Vec<usize> {
         let mut results = self
             .search_engine
             .search(query, limit)
             .into_iter()
-            .filter_map(|result| self.entries.get(result.document.id))
+            .map(|result| result.document.id)
             .collect::<Vec<_>>();
         if !use_default_limit {
             return results;
         }
 
-        if results
-            .iter()
-            .any(|(_, tool)| tool.server_name == COMPUTER_USE_MCP_SERVER_NAME)
-        {
+        if results.iter().any(|&id| {
+            self.mcp_tools
+                .get(id)
+                .is_some_and(|tool| tool.server_name == COMPUTER_USE_MCP_SERVER_NAME)
+        }) {
             results = self
                 .search_engine
                 .search(query, COMPUTER_USE_TOOL_SEARCH_LIMIT)
                 .into_iter()
-                .filter_map(|result| self.entries.get(result.document.id))
+                .map(|result| result.document.id)
                 .collect();
         }
-        limit_results_per_server(results)
+        limit_results_per_server(&self.mcp_tools, results)
+    }
+
+    fn search_output_tools(
+        &self,
+        result_ids: impl IntoIterator<Item = usize>,
+    ) -> Result<Vec<ToolSearchOutputTool>, FunctionCallError> {
+        let mut tools = Vec::new();
+        // Preserve search order: group MCP tools under namespaces, emit dynamic tools directly.
+        for result_id in result_ids {
+            if let Some(info) = self.mcp_tools.get(result_id) {
+                let tool_name = info.canonical_tool_name();
+                let namespace = info.callable_namespace.as_str();
+                let namespace_tool =
+                    mcp_tool_to_deferred_responses_api_tool(&tool_name, &info.tool)
+                        .map(ResponsesApiNamespaceTool::Function)
+                        .map_err(tool_search_output_error)?;
+
+                if let Some(output) = tools.iter_mut().find_map(|tool| match tool {
+                    ToolSearchOutputTool::Namespace(output) if output.name == namespace => {
+                        Some(output)
+                    }
+                    ToolSearchOutputTool::Namespace(_) | ToolSearchOutputTool::Function(_) => None,
+                }) {
+                    output.tools.push(namespace_tool);
+                } else {
+                    tools.push(ToolSearchOutputTool::Namespace(ResponsesApiNamespace {
+                        name: namespace.to_string(),
+                        description: mcp_namespace_description(info),
+                        tools: vec![namespace_tool],
+                    }));
+                }
+                continue;
+            }
+
+            let Some(dynamic_tool_index) = result_id.checked_sub(self.mcp_tools.len()) else {
+                continue;
+            };
+            let Some(tool) = self.dynamic_tools.get(dynamic_tool_index) else {
+                continue;
+            };
+            tools.push(ToolSearchOutputTool::Function(
+                dynamic_tool_to_responses_api_tool(tool).map_err(tool_search_output_error)?,
+            ));
+        }
+
+        Ok(tools)
     }
 }
 
-fn limit_results_per_server(results: Vec<&(String, ToolInfo)>) -> Vec<&(String, ToolInfo)> {
+fn mcp_namespace_description(info: &ToolInfo) -> String {
+    info.connector_description
+        .clone()
+        .or_else(|| {
+            info.connector_name
+                .as_deref()
+                .map(str::trim)
+                .filter(|connector_name| !connector_name.is_empty())
+                .map(|connector_name| format!("Tools for working with {connector_name}."))
+        })
+        .unwrap_or_else(|| format!("Tools from the {} MCP server.", info.server_name))
+}
+
+fn limit_results_per_server(mcp_tools: &[ToolInfo], results: Vec<usize>) -> Vec<usize> {
     results
         .into_iter()
         .scan(
             std::collections::HashMap::<&str, usize>::new(),
-            |counts, entry| {
-                let tool = &entry.1;
-                let count = counts.entry(tool.server_name.as_str()).or_default();
-                if *count >= default_limit_for_server(tool.server_name.as_str()) {
+            |counts, result_id| {
+                let Some(tool) = mcp_tools.get(result_id) else {
+                    return Some(Some(result_id));
+                };
+                let server_name = tool.server_name.as_str();
+                let count = counts.entry(server_name).or_default();
+                if *count >= default_limit_for_server(server_name) {
                     Some(None)
                 } else {
                     *count += 1;
-                    Some(Some(entry))
+                    Some(Some(result_id))
                 }
             },
         )
@@ -165,9 +231,15 @@ fn default_limit_for_server(server_name: &str) -> usize {
     }
 }
 
-fn build_search_text(name: &str, info: &ToolInfo) -> String {
+fn tool_search_output_error(err: serde_json::Error) -> FunctionCallError {
+    FunctionCallError::Fatal(format!(
+        "failed to encode {TOOL_SEARCH_TOOL_NAME} output: {err}"
+    ))
+}
+
+fn build_mcp_search_text(info: &ToolInfo) -> String {
     let mut parts = vec![
-        name.to_string(),
+        info.canonical_tool_name().display(),
         info.callable_name.clone(),
         info.tool.name.to_string(),
         info.server_name.clone(),
@@ -218,22 +290,131 @@ fn build_search_text(name: &str, info: &ToolInfo) -> String {
     parts.join(" ")
 }
 
+fn build_dynamic_search_text(tool: &DynamicToolSpec) -> String {
+    let mut parts = vec![
+        tool.name.clone(),
+        tool.name.replace('_', " "),
+        tool.description.clone(),
+    ];
+
+    parts.extend(
+        tool.input_schema
+            .get("properties")
+            .and_then(serde_json::Value::as_object)
+            .map(|map| map.keys().cloned().collect::<Vec<_>>())
+            .unwrap_or_default(),
+    );
+
+    parts.join(" ")
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use codex_tools::ResponsesApiNamespace;
+    use codex_tools::ResponsesApiNamespaceTool;
+    use codex_tools::ResponsesApiTool;
     use pretty_assertions::assert_eq;
     use rmcp::model::Tool;
     use std::sync::Arc;
 
     #[test]
-    fn computer_use_tool_search_uses_larger_limit() {
-        let handler = ToolSearchHandler::new(numbered_tools(
-            COMPUTER_USE_MCP_SERVER_NAME,
-            "computer use",
-            /*count*/ 100,
-        ));
+    fn mixed_search_results_coalesce_mcp_namespaces() {
+        let handler = ToolSearchHandler::new(
+            std::collections::HashMap::from([
+                (
+                    "mcp__calendar__create_event".to_string(),
+                    tool_info("calendar", "create_event", "Create events"),
+                ),
+                (
+                    "mcp__calendar__list_events".to_string(),
+                    tool_info("calendar", "list_events", "List events"),
+                ),
+            ]),
+            vec![DynamicToolSpec {
+                name: "automation_update".to_string(),
+                description: "Create, update, view, or delete recurring automations.".to_string(),
+                input_schema: serde_json::json!({
+                    "type": "object",
+                    "properties": {
+                        "mode": { "type": "string" },
+                    },
+                    "required": ["mode"],
+                    "additionalProperties": false,
+                }),
+                defer_loading: true,
+            }],
+        );
 
-        let results = handler.search_result_entries(
+        let tools = handler
+            .search_output_tools([0, 2, 1])
+            .expect("mixed search output should serialize");
+
+        assert_eq!(
+            tools,
+            vec![
+                ToolSearchOutputTool::Namespace(ResponsesApiNamespace {
+                    name: "mcp__calendar__".to_string(),
+                    description: "Tools from the calendar MCP server.".to_string(),
+                    tools: vec![
+                        ResponsesApiNamespaceTool::Function(ResponsesApiTool {
+                            name: "create_event".to_string(),
+                            description: "Create events desktop tool".to_string(),
+                            strict: false,
+                            defer_loading: Some(true),
+                            parameters: codex_tools::JsonSchema::object(
+                                Default::default(),
+                                /*required*/ None,
+                                Some(false.into()),
+                            ),
+                            output_schema: None,
+                        }),
+                        ResponsesApiNamespaceTool::Function(ResponsesApiTool {
+                            name: "list_events".to_string(),
+                            description: "List events desktop tool".to_string(),
+                            strict: false,
+                            defer_loading: Some(true),
+                            parameters: codex_tools::JsonSchema::object(
+                                Default::default(),
+                                /*required*/ None,
+                                Some(false.into()),
+                            ),
+                            output_schema: None,
+                        }),
+                    ],
+                }),
+                ToolSearchOutputTool::Function(ResponsesApiTool {
+                    name: "automation_update".to_string(),
+                    description: "Create, update, view, or delete recurring automations."
+                        .to_string(),
+                    strict: false,
+                    defer_loading: Some(true),
+                    parameters: codex_tools::JsonSchema::object(
+                        std::collections::BTreeMap::from([(
+                            "mode".to_string(),
+                            codex_tools::JsonSchema::string(None),
+                        )]),
+                        Some(vec!["mode".to_string()]),
+                        Some(false.into()),
+                    ),
+                    output_schema: None,
+                }),
+            ],
+        );
+    }
+
+    #[test]
+    fn computer_use_tool_search_uses_larger_limit() {
+        let handler = ToolSearchHandler::new(
+            numbered_tools(
+                COMPUTER_USE_MCP_SERVER_NAME,
+                "computer use",
+                /*count*/ 100,
+            ),
+            Vec::new(),
+        );
+
+        let results = handler.search_result_ids(
             "computer use",
             TOOL_SEARCH_DEFAULT_LIMIT,
             /*use_default_limit*/ true,
@@ -243,10 +424,10 @@ mod tests {
         assert!(
             results
                 .iter()
-                .all(|(_, tool)| tool.server_name == COMPUTER_USE_MCP_SERVER_NAME)
+                .all(|&id| handler.mcp_tools[id].server_name == COMPUTER_USE_MCP_SERVER_NAME)
         );
 
-        let explicit_results = handler.search_result_entries(
+        let explicit_results = handler.search_result_ids(
             "computer use",
             /*limit*/ 100,
             /*use_default_limit*/ false,
@@ -267,9 +448,9 @@ mod tests {
             "calendar",
             /*count*/ 100,
         ));
-        let handler = ToolSearchHandler::new(tools);
+        let handler = ToolSearchHandler::new(tools, Vec::new());
 
-        let results = handler.search_result_entries(
+        let results = handler.search_result_ids(
             "calendar",
             TOOL_SEARCH_DEFAULT_LIMIT,
             /*use_default_limit*/ true,
@@ -279,10 +460,10 @@ mod tests {
         assert!(
             results
                 .iter()
-                .all(|(_, tool)| tool.server_name == "other-server")
+                .all(|&id| handler.mcp_tools[id].server_name == "other-server")
         );
 
-        let explicit_results = handler.search_result_entries(
+        let explicit_results = handler.search_result_ids(
             "calendar", /*limit*/ 100, /*use_default_limit*/ false,
         );
 
@@ -301,19 +482,22 @@ mod tests {
             "computer use",
             /*count*/ 100,
         ));
-        let handler = ToolSearchHandler::new(tools);
+        let handler = ToolSearchHandler::new(tools, Vec::new());
 
-        let results = handler.search_result_entries(
+        let results = handler.search_result_ids(
             "computer use",
             TOOL_SEARCH_DEFAULT_LIMIT,
             /*use_default_limit*/ true,
         );
 
         assert!(
-            count_results_for_server(&results, COMPUTER_USE_MCP_SERVER_NAME)
+            count_results_for_server(&handler, &results, COMPUTER_USE_MCP_SERVER_NAME)
                 <= COMPUTER_USE_TOOL_SEARCH_LIMIT
         );
-        assert!(count_results_for_server(&results, "other-server") <= TOOL_SEARCH_DEFAULT_LIMIT);
+        assert!(
+            count_results_for_server(&handler, &results, "other-server")
+                <= TOOL_SEARCH_DEFAULT_LIMIT
+        );
     }
 
     fn numbered_tools(
@@ -360,10 +544,14 @@ mod tests {
         }
     }
 
-    fn count_results_for_server(results: &[&(String, ToolInfo)], server_name: &str) -> usize {
+    fn count_results_for_server(
+        handler: &ToolSearchHandler,
+        results: &[usize],
+        server_name: &str,
+    ) -> usize {
         results
             .iter()
-            .filter(|(_, tool)| tool.server_name == server_name)
+            .filter(|&&id| handler.mcp_tools[id].server_name == server_name)
             .count()
     }
 }

codex-rs/core/src/tools/spec.rs

@@ -157,6 +157,11 @@ pub(crate) fn build_specs_with_discoverable_tools(
     let request_user_input_handler = Arc::new(RequestUserInputHandler {
         default_mode_request_user_input: config.default_mode_request_user_input,
     });
+    let deferred_dynamic_tools = dynamic_tools
+        .iter()
+        .filter(|tool| tool.defer_loading)
+        .cloned()
+        .collect::<Vec<_>>();
     let mut tool_search_handler = None;
     let tool_suggest_handler = Arc::new(ToolSuggestHandler);
     let code_mode_handler = Arc::new(CodeModeExecuteHandler);
@@ -259,9 +264,10 @@ pub(crate) fn build_specs_with_discoverable_tools(
             }
             ToolHandlerKind::ToolSearch => {
                 if tool_search_handler.is_none() {
-                    tool_search_handler = deferred_mcp_tools
-                        .as_ref()
-                        .map(|tools| Arc::new(ToolSearchHandler::new(tools.clone())));
+                    tool_search_handler = Some(Arc::new(ToolSearchHandler::new(
+                        deferred_mcp_tools.clone().unwrap_or_default(),
+                        deferred_dynamic_tools.clone(),
+                    )));
                 }
                 if let Some(tool_search_handler) = tool_search_handler.as_ref() {
                     builder.register_handler(handler.name, tool_search_handler.clone());

codex-rs/core/tests/suite/search_tool.rs

@@ -39,7 +39,7 @@ use std::collections::HashMap;
 use std::time::Duration;
 
 const SEARCH_TOOL_DESCRIPTION_SNIPPETS: [&str; 2] = [
-    "You have access to tools from the following MCP servers/connectors",
+    "You have access to tools from the following sources",
     "- Calendar: Plan events and manage your calendar.",
 ];
 const TOOL_SEARCH_TOOL_NAME: &str = "tool_search";
@@ -177,7 +177,7 @@ async fn search_tool_enabled_by_default_adds_tool_search() -> Result<()> {
             "parameters": {
                 "type": "object",
                 "properties": {
-                    "query": {"type": "string", "description": "Search query for MCP tools."},
+                    "query": {"type": "string", "description": "Search query for deferred tools."},
                     "limit": {"type": "number", "description": "Maximum number of tools to return (defaults to 8)."},
                 },
                 "required": ["query"],

codex-rs/tools/src/tool_discovery.rs

@@ -153,7 +153,7 @@ pub fn create_tool_search_tool(
     let properties = BTreeMap::from([
         (
             "query".to_string(),
-            JsonSchema::string(Some("Search query for MCP tools.".to_string())),
+            JsonSchema::string(Some("Search query for deferred tools.".to_string())),
         ),
         (
             "limit".to_string(),
@@ -189,7 +189,7 @@ pub fn create_tool_search_tool(
     };
 
     let description = format!(
-        "# MCP tool discovery\n\nSearches over MCP tool metadata with BM25 and exposes matching tools for the next model call.\n\nYou have access to tools from the following MCP servers/connectors:\n{source_descriptions}\nSome of the tools may not have been provided to you upfront, and you should use this tool (`{TOOL_SEARCH_TOOL_NAME}`) to search for the required MCP tools. For MCP tool discovery, always use `{TOOL_SEARCH_TOOL_NAME}` instead of `list_mcp_resources` or `list_mcp_resource_templates`."
+        "# Tool discovery\n\nSearches over deferred tool metadata with BM25 and exposes matching tools for the next model call.\n\nYou have access to tools from the following sources:\n{source_descriptions}\nSome of the tools may not have been provided to you upfront, and you should use this tool (`{TOOL_SEARCH_TOOL_NAME}`) to search for the required tools. For MCP tool discovery, always use `{TOOL_SEARCH_TOOL_NAME}` instead of `list_mcp_resources` or `list_mcp_resource_templates`."
     );
 
     ToolSpec::ToolSearch {

codex-rs/tools/src/tool_discovery_tests.rs

@@ -50,7 +50,7 @@ fn create_tool_search_tool_deduplicates_and_renders_enabled_sources() {
         ),
         ToolSpec::ToolSearch {
             execution: "client".to_string(),
-            description: "# MCP tool discovery\n\nSearches over MCP tool metadata with BM25 and exposes matching tools for the next model call.\n\nYou have access to tools from the following MCP servers/connectors:\n- Google Drive: Use Google Drive as the single entrypoint for Drive, Docs, Sheets, and Slides work.\n- docs\nSome of the tools may not have been provided to you upfront, and you should use this tool (`tool_search`) to search for the required MCP tools. For MCP tool discovery, always use `tool_search` instead of `list_mcp_resources` or `list_mcp_resource_templates`.".to_string(),
+            description: "# Tool discovery\n\nSearches over deferred tool metadata with BM25 and exposes matching tools for the next model call.\n\nYou have access to tools from the following sources:\n- Google Drive: Use Google Drive as the single entrypoint for Drive, Docs, Sheets, and Slides work.\n- docs\nSome of the tools may not have been provided to you upfront, and you should use this tool (`tool_search`) to search for the required tools. For MCP tool discovery, always use `tool_search` instead of `list_mcp_resources` or `list_mcp_resource_templates`.".to_string(),
             parameters: JsonSchema::object(BTreeMap::from([
                     (
                         "limit".to_string(),
@@ -61,7 +61,7 @@ fn create_tool_search_tool_deduplicates_and_renders_enabled_sources() {
                     ),
                     (
                         "query".to_string(),
-                        JsonSchema::string(Some("Search query for MCP tools.".to_string()),),
+                        JsonSchema::string(Some("Search query for deferred tools.".to_string()),),
                     ),
                 ]), Some(vec!["query".to_string()]), Some(false.into())),
         }

codex-rs/tools/src/tool_registry_plan.rs

@@ -11,6 +11,7 @@ use crate::ToolHandlerKind;
 use crate::ToolRegistryPlan;
 use crate::ToolRegistryPlanParams;
 use crate::ToolSearchSource;
+use crate::ToolSearchSourceInfo;
 use crate::ToolSpec;
 use crate::ToolsConfig;
 use crate::ViewImageToolOptions;
@@ -251,17 +252,35 @@ pub fn build_tool_registry_plan(
         plan.register_handler("request_permissions", ToolHandlerKind::RequestPermissions);
     }
 
+    let deferred_dynamic_tools = params
+        .dynamic_tools
+        .iter()
+        .filter(|tool| tool.defer_loading)
+        .collect::<Vec<_>>();
+
     if config.search_tool
-        && let Some(deferred_mcp_tools) = params.deferred_mcp_tools
+        && (params.deferred_mcp_tools.is_some() || !deferred_dynamic_tools.is_empty())
     {
-        let search_source_infos =
-            collect_tool_search_source_infos(deferred_mcp_tools.iter().map(|tool| {
-                ToolSearchSource {
-                    server_name: tool.server_name,
-                    connector_name: tool.connector_name,
-                    connector_description: tool.connector_description,
-                }
-            }));
+        let mut search_source_infos = params
+            .deferred_mcp_tools
+            .map(|deferred_mcp_tools| {
+                collect_tool_search_source_infos(deferred_mcp_tools.iter().map(|tool| {
+                    ToolSearchSource {
+                        server_name: tool.server_name,
+                        connector_name: tool.connector_name,
+                        connector_description: tool.connector_description,
+                    }
+                }))
+            })
+            .unwrap_or_default();
+
+        if !deferred_dynamic_tools.is_empty() {
+            search_source_infos.push(ToolSearchSourceInfo {
+                name: "Dynamic tools".to_string(),
+                description: Some("Tools provided by the current Codex thread.".to_string()),
+            });
+        }
+
         plan.push_spec(
             create_tool_search_tool(&search_source_infos, TOOL_SEARCH_DEFAULT_LIMIT),
             /*supports_parallel_tool_calls*/ true,
@@ -269,8 +288,10 @@ pub fn build_tool_registry_plan(
         );
         plan.register_handler(TOOL_SEARCH_TOOL_NAME, ToolHandlerKind::ToolSearch);
 
-        for tool in deferred_mcp_tools {
-            plan.register_handler(tool.name.clone(), ToolHandlerKind::Mcp);
+        if let Some(deferred_mcp_tools) = params.deferred_mcp_tools {
+            for tool in deferred_mcp_tools {
+                plan.register_handler(tool.name.clone(), ToolHandlerKind::Mcp);
+            }
         }
     }
 

codex-rs/tools/src/tool_registry_plan_tests.rs

@@ -1407,6 +1407,57 @@ fn search_tool_requires_model_capability_and_enabled_feature() {
     assert_contains_tool_names(&tools, &[TOOL_SEARCH_TOOL_NAME]);
 }
 
+#[test]
+fn search_tool_registers_for_deferred_dynamic_tools() {
+    let model_info = search_capable_model_info();
+    let mut features = Features::with_defaults();
+    features.enable(Feature::ToolSearch);
+    let available_models = Vec::new();
+    let tools_config = ToolsConfig::new(&ToolsConfigParams {
+        model_info: &model_info,
+        available_models: &available_models,
+        features: &features,
+        image_generation_tool_auth_allowed: true,
+        web_search_mode: Some(WebSearchMode::Cached),
+        session_source: SessionSource::Cli,
+        sandbox_policy: &SandboxPolicy::DangerFullAccess,
+        windows_sandbox_level: WindowsSandboxLevel::Disabled,
+    });
+    let dynamic_tool = DynamicToolSpec {
+        name: "automation_update".to_string(),
+        description: "Create, update, view, or delete recurring automations.".to_string(),
+        input_schema: json!({
+            "type": "object",
+            "properties": {
+                "mode": { "type": "string" },
+            },
+        }),
+        defer_loading: true,
+    };
+
+    let (tools, handlers) = build_specs(
+        &tools_config,
+        /*mcp_tools*/ None,
+        /*deferred_mcp_tools*/ None,
+        &[dynamic_tool],
+    );
+
+    let search_tool = find_tool(&tools, TOOL_SEARCH_TOOL_NAME);
+    let ToolSpec::ToolSearch { description, .. } = &search_tool.spec else {
+        panic!("expected tool_search tool");
+    };
+    assert!(description.contains("- Dynamic tools: Tools provided by the current Codex thread."));
+    assert_contains_tool_names(&tools, &[TOOL_SEARCH_TOOL_NAME, "automation_update"]);
+    assert!(handlers.contains(&ToolHandlerSpec {
+        name: ToolName::plain(TOOL_SEARCH_TOOL_NAME),
+        kind: ToolHandlerKind::ToolSearch,
+    }));
+    assert!(handlers.contains(&ToolHandlerSpec {
+        name: ToolName::plain("automation_update"),
+        kind: ToolHandlerKind::DynamicTool,
+    }));
+}
+
 #[test]
 fn tool_suggest_is_not_registered_without_feature_flag() {
     let model_info = search_capable_model_info();