#4621 [Engine] Responses API: run Codex's client-side tool_search, finds declared where the search answered
closed · @Krischan-Klug · 0 Kommentare · Auf GitHub
Server & APIAMD / HIPNVIDIA / CUDAModels & quantsSecurityDocumentationWindowsLinux
Beschreibung
## Problem and result
With `"supports_search_tool": true` in its model catalog, Codex (CLI and Desktop, Responses wire API) keeps its MCP tools
out of the request and declares its own tool discovery instead: `{"type": "tool_search", "execution": "client", ...}`.
`serve/responses.py` lists `tool_search` in `HOSTED_TOOLS`, so the declaration is dropped (`left out the hosted tools
tool_search`): the model can never reach the tools the client keeps in reserve (#1917).
With this change the model gets `tool_search` as a plain function and its call goes back as a `tool_search_call` that
Codex runs. The tools Codex finds (`tool_search_output`) are declared in that search's tool result, not in the tool list
at the top of the prompt, so the prompt before the search stays the same and the conversation cache holds across the
load.
## Related discussion
#1917 (closed in the 0.2.0 tracker reset: "Closed here does not mean rejected"; this PR carries the re-test). It starts
from #1918 by @msola-ht, which its author closed before review; that behaviour was rebuilt by hand on current `main`
and @msola-ht is co-author of the commit. There is no maintainer agreement on scope yet: happy to change the approach
or split it.
## Approach
- A `tool_search` with `execution: "client"` is declared to the model as the function `tool_search` (once). One without
it stays left out like the other hosted tools: OpenAI's plain `{"type": "tool_search"}` is the server-side variant.
- The model's call becomes a `tool_search_call` output item: `execution: "client"`, `arguments` as an object, no
argument deltas, `incomplete` when the turn is cut off inside it.
- In `input`, a `tool_search_call` is replayed as that `tool_search` call. A `tool_search_output` becomes the call's
tool result and holds the found tools in the template's `<tools>` form (one JSON object per line). The found tools are
added to the parser's tools and the response's names, so a `namespace.name` call comes back with its `namespace`,
but never to the prompt's tool list: it is at the top of the prompt, and adding to it would change the prompt's
start, and drop the cache, with every search.
- In those results a namespace's description is said once in the conversation, before its first found tools (the
request's own tool list keeps its per-tool form), and a tool an earlier search already declared is only named
(`Already available: ...`). Both follow the order the model reads the results (after `_order_tool_results`), so a
result's text never depends on later items.
- `request_tools`' declaration code moved to `_declare` / `_declare_tools`, so the request's tools and the found tools
are declared by the same code.
- The opt-in is the client's own declaration, as for `additional_tools` (#782): no config key, no default changed. A
request without a client-side `tool_search` renders byte-identically; the existing tests pass unchanged.
## Validation
**Passed:**
- `python -m unittest serve.test_responses` on this branch (base `46c152a1`): 48 tests OK, 5 of them new: the
declaration and the hosted variant; the replay with the finds declared in place; a namespace described once and a
tool found again only named, with the results sent back in either order; the prompt start unchanged on the real
template; and an HTTP round trip (search, then a call of a found namespace tool) whose second prompt starts with the
first prompt plus the model's search call.
- `python -m unittest discover -s serve -p "test_*.py" -t .`: 1,221 tests, one error (see Failed).
- Live, Windows 11, RTX 4090 24 GB, Ryzen 9 7900X, 64 GB DDR5, engine 0.1.52, Swift 1.5 IQ3_S, Codex 0.165.0-alpha
(`codex exec` with the Desktop app's codex.exe): the model called `tool_search` ("node_repl js execute javascript"),
Codex returned `mcp__node_repl` (`js_reset`, `js`, `js_add_node_module_dir`), the model called `mcp__node_repl.js`
and answered. First prompt 10,374 tokens with tool search, 10,716 without; the request after the search reused
10,464 tokens (everything up to and including the search call) and read about 600 new ones.
- Codex Desktop on the same machine (MCP for Unity, Blender MCP and fastcrw configured): the search results of two
real threads, re-rendered from their `tool_search_output` items and counted with the pack's tokenizer, take 3,768
and 4,449 tokens. Declaring every find in full with its namespace text before each tool takes 36,003 and 8,036 for
the same items (the first thread found Blender MCP's 12 tools twice, in two parallel searches).
**Failed:**
- `serve.test_winjob.TestWinJob.test_children_end_with_a_killed_server`: `TypeError: argument of type 'NoneType' is not
iterable` in the test's `running()` helper. It fails the same way on this machine with this change stashed (`main` at
`46c152a1`).
**Not run:**
- Linux and macOS; Codex versions other than 0.165.0-alpha; clients other than Codex.
- No CUDA, HIP, SYCL or Metal build: only Python files and docs changed.
## Limits
- Codex decides what is deferred: its MCP tools, and app tools the app marks `defer_loading`. Codex's own tools and the
Desktop app's tools stay inline (about 14,500 of the Desktop's 23,500-token first prompt here).
- Which tools a search returns is Codex's BM25 over its tool metadata; a web-search query also returned Blender MCP's
`search_*_docs` tools.
- `defer_loading` on tools in the request's own `tools` array (hosted-style deferral) is not handled: those tools are
declared in full, as before.
🤖 Generated with [Claude Code](https://claude.com/claude-code)Mehr auf der Site
Links zu Install, Modellen, Releases.