From 0a2a64e94200b03af3901bad4cd918030739c697 Mon Sep 17 00:00:00 2001 From: swastik-oai Date: Wed, 7 Oct 2026 14:22:49 +0000 Subject: [PATCH] Honor tool-description-first ordering in Code Mode (#51704) ## What changed Apply `code_mode_tool_description_first` when preparing nested tool definitions for Code Mode execution and tool search. When enabled, place each tool's description before its namespace description; otherwise, preserve namespace-first ordering. Reuse cached MCP definitions only when both the input schema budget and description-order setting match. ## Testing Extend deferred app tool integration tests to cover both description orders with and without ranked search, including consistency between search results and `ALL_TOOLS`. Extend the MCP cache test to reject reuse when the description-order setting changes. GitOrigin-RevId: 1e3f84d2d95c200aef21ad710d367274b2169b4b --- .../src/tools/code_mode/execute_handler.rs | 7 +++ .../src/tools/code_mode/tool_definitions.rs | 10 ++- codex-rs/core/src/tools/handlers/mcp.rs | 63 ++++++++++++++----- .../core/src/tools/handlers/tool_search.rs | 8 +++ codex-rs/core/src/tools/registry.rs | 2 + codex-rs/core/tests/suite/code_mode.rs | 22 ++++++- codex-rs/tools/src/code_mode.rs | 8 ++- codex-rs/tools/src/code_mode_tests.rs | 2 + 8 files changed, 97 insertions(+), 25 deletions(-) diff --git a/codex-rs/core/src/tools/code_mode/execute_handler.rs b/codex-rs/core/src/tools/code_mode/execute_handler.rs index 75733b9dfa..25661c6c35 100644 --- a/codex-rs/core/src/tools/code_mode/execute_handler.rs +++ b/codex-rs/core/src/tools/code_mode/execute_handler.rs @@ -4,6 +4,7 @@ use crate::tools::context::ToolPayload; use crate::tools::context::boxed_tool_output; use crate::tools::registry::CoreToolRuntime; use crate::tools::registry::ToolExecutor; +use codex_features::Feature; use codex_prompts::ResolvedModelMessages; use codex_tools::IndirectNamespacePrefixes; use codex_tools::ToolName; @@ -55,12 +56,18 @@ impl CodeModeExecuteHandler { .config .code_mode .tool_input_schema_max_bytes; + let tool_description_first = step_context + .turn + .config + .features + .enabled(Feature::CodeModeToolDescriptionFirst); let mut enabled_tools = Vec::with_capacity(self.nested_tool_specs.len()); for (spec, cached_runtime) in &self.nested_tool_specs { let definitions = prepare_code_mode_tool_definitions( cached_runtime.as_deref(), || Cow::Borrowed(spec.as_ref()), code_mode_input_schema_max_bytes, + tool_description_first, ); match definitions { Cow::Borrowed(definitions) => enabled_tools.extend_from_slice(definitions), diff --git a/codex-rs/core/src/tools/code_mode/tool_definitions.rs b/codex-rs/core/src/tools/code_mode/tool_definitions.rs index 84b262319a..568f6dabd6 100644 --- a/codex-rs/core/src/tools/code_mode/tool_definitions.rs +++ b/codex-rs/core/src/tools/code_mode/tool_definitions.rs @@ -1,5 +1,6 @@ //! Prepares nested tool definitions for execution and search. //! Cached definitions stay borrowed; rendered schemas are dropped after augmentation. +//! Description order follows the session-static feature setting. use crate::tools::registry::CoreToolRuntime; use codex_code_mode::ToolDefinition; @@ -10,10 +11,12 @@ pub(crate) fn prepare_code_mode_tool_definitions<'a>( runtime: Option<&'a dyn CoreToolRuntime>, spec: impl FnOnce() -> Cow<'a, ToolSpec>, code_mode_input_schema_max_bytes: Option, + tool_description_first: bool, ) -> Cow<'a, [ToolDefinition]> { - if let Some(definitions) = runtime - .and_then(|runtime| runtime.cached_code_mode_definitions(code_mode_input_schema_max_bytes)) - { + if let Some(definitions) = runtime.and_then(|runtime| { + runtime + .cached_code_mode_definitions(code_mode_input_schema_max_bytes, tool_description_first) + }) { return Cow::Borrowed(definitions); } @@ -21,6 +24,7 @@ pub(crate) fn prepare_code_mode_tool_definitions<'a>( let mut definitions = codex_tools::collect_code_mode_tool_definitions( std::iter::once(spec.as_ref()), code_mode_input_schema_max_bytes, + tool_description_first, ); for definition in &mut definitions { definition.input_schema = None; diff --git a/codex-rs/core/src/tools/handlers/mcp.rs b/codex-rs/core/src/tools/handlers/mcp.rs index 4cce55018f..e165a53ab2 100644 --- a/codex-rs/core/src/tools/handlers/mcp.rs +++ b/codex-rs/core/src/tools/handlers/mcp.rs @@ -51,7 +51,8 @@ const MAX_MCP_NAMESPACE_DESCRIPTION_BYTES: usize = 512 * 1024; pub struct McpHandler { tool_info: ToolInfo, spec: Arc, - code_mode_tool_definitions: OnceLock<(Option, Vec)>, + code_mode_tool_definitions: + OnceLock<(Option, bool, Vec)>, } impl McpHandler { @@ -284,20 +285,29 @@ impl CoreToolRuntime for McpHandler { fn cached_code_mode_definitions( &self, code_mode_input_schema_max_bytes: Option, + tool_description_first: bool, ) -> Option<&[codex_code_mode::ToolDefinition]> { - let (cached_budget, definitions) = self.code_mode_tool_definitions.get_or_init(|| { - let mut definitions = codex_tools::collect_code_mode_tool_definitions( - std::iter::once(self.spec.as_ref()), - code_mode_input_schema_max_bytes, - ); - for definition in &mut definitions { - definition.input_schema = None; - definition.output_schema = None; - } - (code_mode_input_schema_max_bytes, definitions) - }); - // A config change must not reuse descriptions rendered under the previous budget. - (*cached_budget == code_mode_input_schema_max_bytes).then_some(definitions.as_slice()) + let (cached_budget, cached_tool_description_first, definitions) = + self.code_mode_tool_definitions.get_or_init(|| { + let mut definitions = codex_tools::collect_code_mode_tool_definitions( + std::iter::once(self.spec.as_ref()), + code_mode_input_schema_max_bytes, + tool_description_first, + ); + for definition in &mut definitions { + definition.input_schema = None; + definition.output_schema = None; + } + ( + code_mode_input_schema_max_bytes, + tool_description_first, + definitions, + ) + }); + // Reuse definitions only when both rendering inputs match. + (*cached_budget == code_mode_input_schema_max_bytes + && *cached_tool_description_first == tool_description_first) + .then_some(definitions.as_slice()) } fn wait_until_ready<'a>(&'a self, session: &'a Arc) -> Option> { @@ -833,17 +843,36 @@ mod tests { )); let first = handler - .cached_code_mode_definitions(/*code_mode_input_schema_max_bytes*/ None) + .cached_code_mode_definitions( + /*code_mode_input_schema_max_bytes*/ None, + /*tool_description_first*/ false, + ) .expect("MCP definitions should be cached"); assert_eq!(first.len(), 1); assert!(first[0].input_schema.is_none()); assert!(first[0].output_schema.is_none()); + assert!( + handler + .cached_code_mode_definitions( + /*code_mode_input_schema_max_bytes*/ None, + /*tool_description_first*/ true, + ) + .is_none() + ); + let second = handler - .cached_code_mode_definitions(/*code_mode_input_schema_max_bytes*/ None) + .cached_code_mode_definitions( + /*code_mode_input_schema_max_bytes*/ None, + /*tool_description_first*/ false, + ) .expect("MCP definitions should be cached"); assert!(std::ptr::eq(first, second)); - assert!(handler.cached_code_mode_definitions(Some(32_000)).is_none()); + assert!( + handler + .cached_code_mode_definitions(Some(32_000), /*tool_description_first*/ false) + .is_none() + ); } #[test] diff --git a/codex-rs/core/src/tools/handlers/tool_search.rs b/codex-rs/core/src/tools/handlers/tool_search.rs index 570b6610a2..6fe3c7dfe7 100644 --- a/codex-rs/core/src/tools/handlers/tool_search.rs +++ b/codex-rs/core/src/tools/handlers/tool_search.rs @@ -15,6 +15,7 @@ use bm25::Embedder; use bm25::EmbedderBuilder; use bm25::Language; use bm25::Scorer; +use codex_features::Feature; use codex_prompts::ResolvedModelMessages; use codex_tools::IndirectNamespacePrefixes; use codex_tools::JsonToolOutput; @@ -259,6 +260,11 @@ impl ToolSearchHandler { .config .code_mode .tool_input_schema_max_bytes, + step_context + .turn + .config + .features + .enabled(Feature::CodeModeToolDescriptionFirst), &indirect_prefixes, ); return Ok(boxed_tool_output(JsonToolOutput::new(serde_json::json!({ @@ -286,6 +292,7 @@ impl ToolSearchHandler { limit: usize, router: &ToolRouter, code_mode_input_schema_max_bytes: Option, + tool_description_first: bool, indirect_prefixes: &IndirectNamespacePrefixes<'_>, ) -> Vec { let mut tools = Vec::new(); @@ -313,6 +320,7 @@ impl ToolSearchHandler { Some(runtime.as_ref()), || Cow::Owned(runtime.spec()), code_mode_input_schema_max_bytes, + tool_description_first, ); let Some(definition) = definitions.iter().find(|definition| { definition.tool_name.clone().with_default_namespace() == candidate_name diff --git a/codex-rs/core/src/tools/registry.rs b/codex-rs/core/src/tools/registry.rs index ad51f77d73..da679ce292 100644 --- a/codex-rs/core/src/tools/registry.rs +++ b/codex-rs/core/src/tools/registry.rs @@ -72,9 +72,11 @@ pub(crate) trait CoreToolRuntime: ToolExecutor { /// Returns lazily cached, augmented Code Mode definitions owned by this runtime. /// Input and output schemas must be cleared after rendering their declarations. + /// Return None when the requested rendering inputs differ from the cached inputs. fn cached_code_mode_definitions( &self, _code_mode_input_schema_max_bytes: Option, + _tool_description_first: bool, ) -> Option<&[codex_code_mode::ToolDefinition]> { None } diff --git a/codex-rs/core/tests/suite/code_mode.rs b/codex-rs/core/tests/suite/code_mode.rs index 3452a3939e..2b82def2b0 100644 --- a/codex-rs/core/tests/suite/code_mode.rs +++ b/codex-rs/core/tests/suite/code_mode.rs @@ -3611,12 +3611,15 @@ async fn code_mode_complete_call_survives_unrelated_truncation() -> Result<()> { } #[tokio::test(flavor = "multi_thread", worker_threads = 2)] -#[test_case(false, None; "control")] -#[test_case(true, None; "ranked_search")] -#[test_case(true, Some(30_000); "ranked_search_expanded_schema")] +#[test_case(false, None, false; "control")] +#[test_case(true, None, false; "ranked_search")] +#[test_case(true, Some(30_000), false; "ranked_search_expanded_schema")] +#[test_case(false, None, true; "tool_description_first")] +#[test_case(true, None, true; "ranked_search_tool_description_first")] async fn code_mode_only_searches_and_calls_deferred_app_tools( ranked_search: bool, schema_max_bytes: Option, + tool_description_first: bool, ) -> Result<()> { skip_if_no_network!(Ok(())); @@ -3675,6 +3678,7 @@ if (!tool) { hasDeclaration: tool.description.includes("mcp__codex_apps__calendar_timezone_option_99(args:"), hasSchemaDescription: tool.description.includes("schema_budget_marker"), hasNamespacePrefix: tool.description.startsWith("Calendar search context.\n\n"), + descriptionPrefix: tool.description.split("\n\nexec tool declaration:")[0], matchesCatalog: tool.description === ALL_TOOLS.find(({ name }) => name === tool.name)?.description, isError: Boolean(result.isError), text: result.content?.[0]?.text ?? "", @@ -3735,6 +3739,13 @@ if (!tool) { .enable(Feature::CodeModeOnly) .expect("test config should allow feature update"); config.code_mode.tool_input_schema_max_bytes = schema_max_bytes; + config + .features + .set_enabled( + Feature::CodeModeToolDescriptionFirst, + tool_description_first, + ) + .expect("test config should allow description order update"); if ranked_search { config .features @@ -3822,6 +3833,11 @@ if (!tool) { "hasDeclaration": true, "hasSchemaDescription": schema_max_bytes.is_some(), "hasNamespacePrefix": true, + "descriptionPrefix": if tool_description_first { + "Calendar search context.\n\nRead timezone option 99.\n\nPlan events and manage your calendar." + } else { + "Calendar search context.\n\nPlan events and manage your calendar.\n\nRead timezone option 99." + }, "matchesCatalog": true, "isError": false, "text": "called calendar_timezone_option_99 for at with ", diff --git a/codex-rs/tools/src/code_mode.rs b/codex-rs/tools/src/code_mode.rs index 8194387921..cc0b5326e4 100644 --- a/codex-rs/tools/src/code_mode.rs +++ b/codex-rs/tools/src/code_mode.rs @@ -90,6 +90,7 @@ pub fn tool_spec_to_code_mode_tool_definition(spec: &ToolSpec) -> Option( specs: impl IntoIterator, code_mode_input_schema_max_bytes: Option, + tool_description_first: bool, ) -> Vec { let mut tool_definitions = specs .into_iter() @@ -100,8 +101,11 @@ pub fn collect_code_mode_tool_definitions<'a>( let namespace_description = namespace.description.trim(); if !namespace_description.is_empty() { for definition in &mut definitions { - definition.description = - format!("{namespace_description}\n\n{}", definition.description); + definition.description = if tool_description_first { + format!("{}\n\n{namespace_description}", definition.description) + } else { + format!("{namespace_description}\n\n{}", definition.description) + }; } } } diff --git a/codex-rs/tools/src/code_mode_tests.rs b/codex-rs/tools/src/code_mode_tests.rs index 0486372a5c..9ee63c93da 100644 --- a/codex-rs/tools/src/code_mode_tests.rs +++ b/codex-rs/tools/src/code_mode_tests.rs @@ -58,10 +58,12 @@ fn code_mode_materializes_mcp_output_schemas() { super::collect_code_mode_tool_definitions( [&ToolSpec::Function(parsed)], /*code_mode_input_schema_max_bytes*/ None, + /*tool_description_first*/ false, ), super::collect_code_mode_tool_definitions( [&ToolSpec::Function(eager)], /*code_mode_input_schema_max_bytes*/ None, + /*tool_description_first*/ false, ), ); }