From d256e7b01cc2f5f1ce15eb879036ec6ede71add0 Mon Sep 17 00:00:00 2001
From: Steven Lee <stevenlee@openai.com>
Date: Fri, 26 Jun 2026 16:09:12 +0000
Subject: [PATCH] Mark tool search RPC as debug-only

---
 .../src/protocol/common.rs                    | 29 +++++++++++++++++--
 codex-rs/app-server/README.md                 |  2 +-
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/codex-rs/app-server-protocol/src/protocol/common.rs b/codex-rs/app-server-protocol/src/protocol/common.rs
index 33f0869006..60e9be7b83 100644
--- a/codex-rs/app-server-protocol/src/protocol/common.rs
+++ b/codex-rs/app-server-protocol/src/protocol/common.rs
@@ -969,8 +969,8 @@ client_request_definitions! {
         response: v2::ListMcpServerStatusResponse,
     },
 
-    #[experimental("toolSearch/search")]
-    ToolSearchSearch => "toolSearch/search" {
+    #[experimental("toolSearch/debug/search")]
+    ToolSearchSearch => "toolSearch/debug/search" {
         params: v2::ToolSearchSearchParams,
         serialization: thread_id(params.thread_id),
         response: v2::ToolSearchSearchResponse,
@@ -3012,6 +3012,31 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn serialize_tool_search_debug_search() -> Result<()> {
+        let request = ClientRequest::ToolSearchSearch {
+            request_id: RequestId::Integer(9),
+            params: v2::ToolSearchSearchParams {
+                thread_id: "thread-123".to_string(),
+                query: "openai_topics.list_topics".to_string(),
+                limit: Some(8),
+            },
+        };
+        assert_eq!(
+            json!({
+                "method": "toolSearch/debug/search",
+                "id": 9,
+                "params": {
+                    "threadId": "thread-123",
+                    "query": "openai_topics.list_topics",
+                    "limit": 8
+                }
+            }),
+            serde_json::to_value(&request)?,
+        );
+        Ok(())
+    }
+
     #[test]
     fn serialize_environment_add() -> Result<()> {
         let request = ClientRequest::EnvironmentAdd {
diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.md
index 428b59e26a..d50a1a3cc2 100644
--- a/codex-rs/app-server/README.md
+++ b/codex-rs/app-server/README.md
@@ -234,7 +234,7 @@ Example with notification opt-out:
 - `tool/requestUserInput` — prompt the user with 1–3 short questions for a tool call and return their answers (experimental).
 - `config/mcpServer/reload` — reload MCP server config from disk and queue a refresh for loaded threads (applied on each thread's next active turn); returns `{}`. Use this after editing `config.toml` without restarting the server.
 - `mcpServerStatus/list` — enumerate configured MCP servers with their tools, auth status, server info, plus resources/resource templates for `full` detail; supports optional `threadId` and cursor+limit pagination. If `threadId` is omitted, the server reads from the latest global config directly. If `detail` is omitted, the server defaults to `full`.
-- `toolSearch/search` — experimental; run the current runtime `tool_search` path for a thread by `threadId`, `query`, and optional `limit`, returning the exact coalesced tools payload plus debug metadata such as indexed/matching counts, truncation, rank, score, source, and searchable text.
+- `toolSearch/debug/search` — experimental; run the current runtime `tool_search` path for a thread by `threadId`, `query`, and optional `limit`, returning the exact coalesced tools payload plus debug metadata such as indexed/matching counts, truncation, rank, score, source, and searchable text.
 - `mcpServer/resource/read` — read a resource from a configured MCP server by optional `threadId`, `server`, and `uri`, returning text/blob resource `contents`. If `threadId` is omitted, the server reads from the latest MCP config directly.
 - `mcpServer/tool/call` — call a tool on a thread's configured MCP server by `threadId`, `server`, `tool`, optional `arguments`, and optional `_meta`, returning the MCP tool result.
 - `windowsSandbox/setupStart` — start Windows sandbox setup for the selected mode (`elevated` or `unelevated`); accepts an optional absolute `cwd` to target setup for a specific workspace, returns `{ started: true }` immediately, and later emits `windowsSandbox/setupCompleted`.