Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Honor tool-description-first ordering in Code Mode (#51704)

swastik-oai0a2a64e94200
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<usize>,
+ 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<ToolSpec>,
- code_mode_tool_definitions: OnceLock<(Option<usize>, Vec<codex_code_mode::ToolDefinition>)>,
+ code_mode_tool_definitions:
+ OnceLock<(Option<usize>, bool, Vec<codex_code_mode::ToolDefinition>)>,
}
impl McpHandler {
@@ -284,20 +285,29 @@ impl CoreToolRuntime for McpHandler {
fn cached_code_mode_definitions(
&self,
code_mode_input_schema_max_bytes: Option<usize>,
+ 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<Session>) -> Option<BoxFuture<'a, ()>> {
@@ -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<usize>,
+ tool_description_first: bool,
indirect_prefixes: &IndirectNamespacePrefixes<'_>,
) -> Vec<CodeModeSearchResult> {
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<ToolInvocation> {
/// 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<usize>,
+ _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<usize>,
+ 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<CodeMod
pub fn collect_code_mode_tool_definitions<'a>(
specs: impl IntoIterator<Item = &'a ToolSpec>,
code_mode_input_schema_max_bytes: Option<usize>,
+ tool_description_first: bool,
) -> Vec<CodeModeToolDefinition> {
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,
),
);
}