Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(agent): auto-load searched tools and self-heal unloaded tool calls (#4606)

teoef5c70eb6304
diff --git a/js/app/packages/service-clients/service-cognition/generated/tools/schemas.ts b/js/app/packages/service-clients/service-cognition/generated/tools/schemas.ts
index 38cf80d0a9..134cfdf2cd 100644
--- a/js/app/packages/service-clients/service-cognition/generated/tools/schemas.ts
+++ b/js/app/packages/service-clients/service-cognition/generated/tools/schemas.ts
@@ -1985,6 +1985,9 @@ export const RenameDocumentResponse = z.object({
export const SearchTools = z.object({ query: z.string() });
export const SearchToolsResponse = z.object({
+ additional_matches: z.array(
+ z.object({ description: z.string(), name: z.string() })
+ ),
results: z.array(z.object({ description: z.string(), name: z.string() })),
});
diff --git a/js/app/packages/service-clients/service-cognition/generated/tools/types.ts b/js/app/packages/service-clients/service-cognition/generated/tools/types.ts
index 719549d4ef..9ffa0cd33a 100644
--- a/js/app/packages/service-clients/service-cognition/generated/tools/types.ts
+++ b/js/app/packages/service-clients/service-cognition/generated/tools/types.ts
@@ -1757,8 +1757,8 @@ export interface LoadToolsResponse {
not_found: string[];
}
/**
- * A tool surfaced by [`SearchTools`] or loaded by [`LoadTools`] — just enough
- * for the model to decide whether to load it and how to call it.
+ * A tool surfaced by [`SearchTools`] / [`LoadTools`] — just enough for the
+ * model to decide how to call it.
*/
export interface ToolMatch {
/**
@@ -1766,7 +1766,7 @@ export interface ToolMatch {
*/
description: string;
/**
- * The exact name to load and then call the tool by.
+ * The exact name to call the tool by.
*/
name: string;
}
@@ -2616,7 +2616,7 @@ export interface SearchToolResponse {
results: UnifiedSearchResponseItem[];
}
/**
- * Find tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub) by keyword. Returns matching tools' names and descriptions but does NOT load them — pass the names you want to `LoadTools` to make them callable. Searching is cheap, so cast a wide net.
+ * Find tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub) by keyword. The top matches are loaded automatically: call them by exact name on your next step. Matches past the auto-load cap come back under `additional_matches` and need `LoadTools` first. Searching is cheap, so cast a wide net.
*/
export interface SearchTools {
/**
@@ -2625,12 +2625,19 @@ export interface SearchTools {
query: string;
}
/**
- * Response from [`SearchTools`]: matching tools (name + description), not yet
- * loaded.
+ * Response from [`SearchTools`]: ranked matches, split into the top matches
+ * (auto-loaded, callable on the next model turn) and the remainder (loadable
+ * via [`LoadTools`]).
*/
export interface SearchToolsResponse {
/**
- * Tools matching the query. Call `LoadTools` with the names you want to use.
+ * Matches past the auto-load cap, ranked. Not callable yet — pass a name
+ * to `LoadTools` if one of these is the tool you need.
+ */
+ additional_matches: ToolMatch[];
+ /**
+ * Top matches, ranked by relevance. These are loaded: call them by exact
+ * name on the next step.
*/
results: ToolMatch[];
}
diff --git a/rust/cloud-storage/agent/src/hook.rs b/rust/cloud-storage/agent/src/hook.rs
index e5dc797991..d66717e587 100644
--- a/rust/cloud-storage/agent/src/hook.rs
+++ b/rust/cloud-storage/agent/src/hook.rs
@@ -3,7 +3,9 @@
use crate::AgentError;
use crate::stream::{McpInfo, StreamPart, ToolCall, ToolResponse, Usage};
use ai_toolset::{SearchableTool, ToolInfo};
-use rig_core::agent::{HookAction, PromptHook, ToolCallHookAction};
+use rig_core::agent::{
+ HookAction, InvalidToolCallContext, InvalidToolCallHookAction, PromptHook, ToolCallHookAction,
+};
use rig_core::completion::{CompletionModel, GetTokenUsage};
use rig_core::message::Message;
use std::future::Future;
@@ -30,6 +32,15 @@ pub type RegisterFn =
static CANCELLED_REASON: &str = "user cancelled";
+/// Retry budget for invalid tool calls recovered via
+/// [`StreamBridge::on_invalid_tool_call`]. Lets the common one-shot recovery —
+/// the model calls a searchable tool it never loaded, the bridge loads it, the
+/// call is retried — succeed, while bounding a model that keeps emitting names
+/// that don't exist anywhere. Past the budget the stream fails with
+/// `UnknownToolCall`, as it did before recovery existed. Retries also consume
+/// multi-turn depth.
+pub(crate) const MAX_INVALID_TOOL_CALL_RETRIES: usize = 2;
+
/// Sends [`StreamPart`] items through an unbounded channel as the RIG agentic
/// loop produces events.
#[derive(Clone)]
@@ -41,6 +52,10 @@ pub struct StreamBridge {
loaded_buffer: Arc<Mutex<Vec<SearchableTool>>>,
/// Registers drained tools with the live tool server.
register_loaded: RegisterFn,
+ /// The session's full searchable catalog. Read by
+ /// [`Self::on_invalid_tool_call`] to recover calls to tools the model
+ /// discovered but never loaded.
+ searchable_catalog: Arc<Vec<SearchableTool>>,
/// the user has requested the stream stop
cancel: CancellationToken,
}
@@ -57,6 +72,7 @@ impl StreamBridge {
routing: ToolRouter,
loaded_buffer: Arc<Mutex<Vec<SearchableTool>>>,
register_loaded: RegisterFn,
+ searchable_catalog: Arc<Vec<SearchableTool>>,
cancel: CancellationToken,
) -> (
Self,
@@ -69,6 +85,7 @@ impl StreamBridge {
routing,
loaded_buffer,
register_loaded,
+ searchable_catalog,
cancel,
},
rx,
@@ -101,6 +118,47 @@ where
}
}
+ /// Recover a tool call the model emitted for a tool that is not advertised
+ /// this turn, instead of rig's default fail-fast (which killed the whole
+ /// stream and surfaced to the user as a turn that announced a tool call and
+ /// then went silent).
+ ///
+ /// If the name exists in the searchable catalog — the model discovered it
+ /// via `SearchTools` (possibly in an earlier conversation turn) but it was
+ /// never loaded — load it now and ask the model to retry; the next request
+ /// is rebuilt from the live tool server, so the retried call is valid. For
+ /// names that exist nowhere, the retry feedback points the model at
+ /// `SearchTools` instead of failing the stream on a hallucinated name.
+ async fn on_invalid_tool_call(
+ &self,
+ context: &InvalidToolCallContext,
+ ) -> InvalidToolCallHookAction {
+ match self
+ .searchable_catalog
+ .iter()
+ .find(|tool| tool.name == context.tool_name)
+ {
+ Some(tool) => {
+ (self.register_loaded)(vec![tool.clone()]).await;
+ tracing::info!(
+ tool = %context.tool_name,
+ "auto-loaded searchable tool the model called without loading"
+ );
+ InvalidToolCallHookAction::retry(format!(
+ "The tool `{}` exists but was not loaded when you called it. \
+ It is loaded now — call it again with the same arguments.",
+ context.tool_name
+ ))
+ }
+ None => InvalidToolCallHookAction::retry(format!(
+ "Unknown tool `{}`: no tool with that name exists in this session \
+ or its connected integrations. Use `SearchTools` to find the \
+ right tool, or continue without it.",
+ context.tool_name
+ )),
+ }
+ }
+
async fn on_tool_call(
&self,
tool_name: &str,
diff --git a/rust/cloud-storage/agent/src/model/router.rs b/rust/cloud-storage/agent/src/model/router.rs
index dd0106e761..f5bce2c2d3 100644
--- a/rust/cloud-storage/agent/src/model/router.rs
+++ b/rust/cloud-storage/agent/src/model/router.rs
@@ -416,6 +416,7 @@ where
routing,
loaded_buffer,
register_loaded,
+ request_context.searchable_tools.clone(),
request_context.cancel.clone(),
);
// Driver-side sender for parts derived from rig stream items (thinking,
@@ -427,6 +428,7 @@ where
.stream_prompt(prompt)
.with_history(history)
.multi_turn(max_turns)
+ .max_invalid_tool_call_retries(crate::hook::MAX_INVALID_TOOL_CALL_RETRIES)
.with_hook(bridge)
.await;
diff --git a/rust/cloud-storage/agent/src/test/agent_loop/mod.rs b/rust/cloud-storage/agent/src/test/agent_loop/mod.rs
index 4f96400aa9..3ac84396f4 100644
--- a/rust/cloud-storage/agent/src/test/agent_loop/mod.rs
+++ b/rust/cloud-storage/agent/src/test/agent_loop/mod.rs
@@ -8,3 +8,4 @@ mod util;
mod test_cooperative_cancellation;
mod test_eager_tools;
mod test_tool;
+mod test_tool_search;
diff --git a/rust/cloud-storage/agent/src/test/agent_loop/test_tool_search.rs b/rust/cloud-storage/agent/src/test/agent_loop/test_tool_search.rs
new file mode 100644
index 0000000000..629a775ea6
--- /dev/null
+++ b/rust/cloud-storage/agent/src/test/agent_loop/test_tool_search.rs
@@ -0,0 +1,337 @@
+//! Repro: multiple MCP calls in a single execution from *different* providers.
+//!
+//! Simulates the DCS `CombinedToolSet` wiring: static tools (a LoadTools
+//! stand-in) plus a searchable catalog of MCP tools mangled as
+//! `mcp__<server>__<tool>` from two different servers. The scripted model
+//! loads tools from both servers and then calls one tool from each.
+
+use super::util;
+use crate::stream::ToolResponse;
+use ai_toolset::{
+ AsyncTool, AsyncToolCollection, RequestContext, RequestSchema, SearchableTool, ServiceContext,
+ ToolResult, ToolSet as AiToolSet, ToolSetError,
+};
+use async_trait::async_trait;
+use rig_core::test_utils::{MockCompletionModel, MockStreamEvent};
+use schemars::{JsonSchema, Schema};
+use serde::Deserialize;
+use std::pin::Pin;
+use std::sync::Arc;
+
+/// Stand-in for `ai_tools::SearchTools`: returns all tools and stages them so
+/// they are callable on the next model turn. (The real tool auto-loads only
+/// the top-ranked matches; with this test catalog everything fits the cap.)
+#[derive(Deserialize, JsonSchema)]
+#[schemars(
+ title = "search_tools",
+ description = "Find and stage searchable tools."
+)]
+struct SearchToolsTest {}
+
+#[async_trait]
+impl AsyncTool<()> for SearchToolsTest {
+ type Output = serde_json::Value;
+
+ async fn call(
+ &self,
+ _service_context: ServiceContext<()>,
+ request_context: RequestContext,
+ ) -> ToolResult<Self::Output> {
+ let matched: Vec<SearchableTool> =
+ request_context.searchable_tools.iter().cloned().collect();
+ let results: Vec<String> = matched.iter().map(|t| t.name.clone()).collect();
+ if let Some(loader) = request_context.tool_loader.as_ref() {
+ loader.load(matched);
+ }
+ Ok(serde_json::json!({ "results": results }))
+ }
+}
+
+/// Stand-in for `ai_tools::LoadTools`: looks names up in the request context's
+/// searchable catalog and hands them to the loader.
+#[derive(Deserialize, JsonSchema)]
+#[schemars(title = "load_tools", description = "Load searchable tools by name.")]
+struct LoadToolsTest {
+ names: Vec<String>,
+}
+
+#[async_trait]
+impl AsyncTool<()> for LoadToolsTest {
+ type Output = serde_json::Value;
+
+ async fn call(
+ &self,
+ _service_context: ServiceContext<()>,
+ request_context: RequestContext,
+ ) -> ToolResult<Self::Output> {
+ let matched: Vec<SearchableTool> = request_context
+ .searchable_tools
+ .iter()
+ .filter(|t| self.names.contains(&t.name))
+ .cloned()
+ .collect();
+ let loaded: Vec<String> = matched.iter().map(|t| t.name.clone()).collect();
+ if let Some(loader) = request_context.tool_loader.as_ref() {
+ loader.load(matched);
+ }
+ Ok(serde_json::json!({ "loaded": loaded }))
+ }
+}
+
+/// Fake `CombinedToolSet`: static tools + a searchable MCP catalog spanning
+/// two servers (`a` and `b`).
+struct FakeCombined {
+ static_tools: Arc<AsyncToolCollection<()>>,
+ mcp_tools: Vec<String>,
+}
+
+impl FakeCombined {
+ fn new() -> Self {
+ Self {
+ static_tools: Arc::new(
+ AsyncToolCollection::<()>::new()
+ .add_tool::<SearchToolsTest, ()>()
+ .add_tool::<LoadToolsTest, ()>(),
+ ),
+ mcp_tools: vec!["mcp__a__t1".to_owned(), "mcp__b__t2".to_owned()],
+ }
+ }
+}
+
+impl AiToolSet<()> for FakeCombined {
+ fn try_tool_call<'a>(
+ &'a self,
+ context: (),
+ request_context: RequestContext,
+ tool_name: &'a str,
+ json: &'a serde_json::Value,
+ ) -> Pin<
+ Box<dyn Future<Output = Result<ToolResult<serde_json::Value>, ToolSetError>> + 'a + Send>,
+ > {
+ if tool_name.starts_with("mcp__") {
+ let known = self.mcp_tools.iter().any(|t| t == tool_name);
+ let name = tool_name.to_owned();
+ return Box::pin(async move {
+ if known {
+ Ok(Ok(serde_json::json!({ "ok": name })))
+ } else {
+ Err(ToolSetError::NotFound(name))
+ }
+ });
+ }
+ self.static_tools
+ .try_tool_call(context, request_context, tool_name, json)
+ }
+
+ fn request_schemas(&self) -> Option<Vec<RequestSchema>> {
+ self.static_tools.request_schemas()
+ }
+
+ fn searchable_catalog(&self) -> Vec<SearchableTool> {
+ self.mcp_tools
+ .iter()
+ .map(|name| SearchableTool {
+ name: name.clone(),
+ description: format!("tool {name}"),
+ schema: Schema::default(),
+ })
+ .collect()
+ }
+
+ fn searchable_toolset_names(&self) -> Vec<String> {
+ vec!["a".to_owned(), "b".to_owned()]
+ }
+}
+
+fn expect_json_ok(result: &util::Collected, tool: &str) {
+ let response = result
+ .tool_responses()
+ .into_iter()
+ .find(|r| matches!(r, ToolResponse::Json { name, .. } | ToolResponse::Err { name, .. } if name == tool));
+ match response {
+ Some(ToolResponse::Json { json, .. }) => {
+ assert_eq!(*json, serde_json::json!({ "ok": tool }), "for {tool}");
+ }
+ other => panic!("expected success response for {tool}, got {other:?}"),
+ }
+}
+
+/// Load tools from two servers in one LoadTools call, then call one tool from
+/// each server in a single subsequent turn.
+#[tokio::test]
+async fn mcp_calls_from_two_providers_in_one_turn() {
+ let model = MockCompletionModel::from_stream_turns([
+ vec![
+ MockStreamEvent::tool_call(
+ "call-load",
+ "load_tools",
+ serde_json::json!({ "names": ["mcp__a__t1", "mcp__b__t2"] }),
+ ),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![
+ MockStreamEvent::tool_call("call-a", "mcp__a__t1", serde_json::json!({})),
+ MockStreamEvent::tool_call("call-b", "mcp__b__t2", serde_json::json!({})),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![MockStreamEvent::final_response_with_default_usage()],
+ ]);
+
+ let toolset: Arc<dyn AiToolSet<()> + Send + Sync> = Arc::new(FakeCombined::new());
+ let mut session = util::session(toolset, Arc::new(()), model).await;
+ let result = util::drive(&mut session, "use both integrations").await;
+
+ assert!(
+ result.error.is_none(),
+ "stream ended with error: {:?}",
+ result.error
+ );
+ expect_json_ok(&result, "mcp__a__t1");
+ expect_json_ok(&result, "mcp__b__t2");
+}
+
+/// Searching stages all matches, so the following turn can call tools from
+/// multiple providers without first spending a separate `LoadTools` turn.
+#[tokio::test]
+async fn search_stages_tools_from_multiple_providers_for_the_next_turn() {
+ let model = MockCompletionModel::from_stream_turns([
+ vec![
+ MockStreamEvent::tool_call("call-search", "search_tools", serde_json::json!({})),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![
+ MockStreamEvent::tool_call("call-a", "mcp__a__t1", serde_json::json!({})),
+ // The model may redundantly call LoadTools and the tool in the same
+ // turn. Because SearchTools already staged it, the tool is in this
+ // turn's normal allowed set and no invalid-call recovery is needed.
+ MockStreamEvent::tool_call(
+ "call-load-b",
+ "load_tools",
+ serde_json::json!({ "names": ["mcp__b__t2"] }),
+ ),
+ MockStreamEvent::tool_call("call-b", "mcp__b__t2", serde_json::json!({})),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![MockStreamEvent::final_response_with_default_usage()],
+ ]);
+
+ let toolset: Arc<dyn AiToolSet<()> + Send + Sync> = Arc::new(FakeCombined::new());
+ let mut session = util::session(toolset, Arc::new(()), model).await;
+ let result = util::drive(&mut session, "search, then use both integrations").await;
+
+ assert!(
+ result.error.is_none(),
+ "stream ended with error: {:?}",
+ result.error
+ );
+ expect_json_ok(&result, "mcp__a__t1");
+ expect_json_ok(&result, "mcp__b__t2");
+}
+
+/// Repro for the reported "silent empty-turn stall": the model calls an
+/// integration tool that exists in the searchable catalog but was never
+/// loaded, so it is not advertised this turn. Instead of the stream dying with
+/// `UnknownToolCall` (surfaced to the user as a turn that announced a tool
+/// call and then went silent), the bridge loads the tool from the catalog and
+/// the retried call succeeds.
+#[tokio::test]
+async fn calling_a_searchable_tool_before_loading_self_heals() {
+ let model = MockCompletionModel::from_stream_turns([
+ // Calls the tool directly, skipping search/load entirely.
+ vec![
+ MockStreamEvent::tool_call("call-a", "mcp__a__t1", serde_json::json!({})),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ // Retry turn: the tool is loaded now; the same call goes through.
+ vec![
+ MockStreamEvent::tool_call("call-a-retry", "mcp__a__t1", serde_json::json!({})),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![MockStreamEvent::final_response_with_default_usage()],
+ ]);
+
+ let toolset: Arc<dyn AiToolSet<()> + Send + Sync> = Arc::new(FakeCombined::new());
+ let mut session = util::session(toolset, Arc::new(()), model).await;
+ let result = util::drive(&mut session, "use integration a without loading it").await;
+
+ assert!(
+ result.error.is_none(),
+ "stream ended with error: {:?}",
+ result.error
+ );
+ expect_json_ok(&result, "mcp__a__t1");
+}
+
+/// A call to a name that exists nowhere — not even the searchable catalog —
+/// feeds corrective feedback back to the model instead of failing the stream;
+/// the model recovers and finishes the turn normally.
+#[tokio::test]
+async fn hallucinated_tool_name_gets_feedback_and_the_turn_recovers() {
+ let model = MockCompletionModel::from_stream_turns([
+ vec![
+ MockStreamEvent::tool_call("call-bad", "mcp__zz__nope", serde_json::json!({})),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ // Retry turn: the model answers in text instead.
+ vec![
+ MockStreamEvent::text("recovered without the tool"),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ ]);
+
+ let toolset: Arc<dyn AiToolSet<()> + Send + Sync> = Arc::new(FakeCombined::new());
+ let mut session = util::session(toolset, Arc::new(()), model).await;
+ let result = util::drive(&mut session, "use a tool that does not exist").await;
+
+ assert!(
+ result.error.is_none(),
+ "stream ended with error: {:?}",
+ result.error
+ );
+ assert!(result.tool_responses().is_empty());
+ assert!(result.content().contains("recovered without the tool"));
+}
+
+/// Load + call server a, then load + call server b, all in one execution.
+#[tokio::test]
+async fn mcp_calls_from_two_providers_loaded_sequentially() {
+ let model = MockCompletionModel::from_stream_turns([
+ vec![
+ MockStreamEvent::tool_call(
+ "call-load-a",
+ "load_tools",
+ serde_json::json!({ "names": ["mcp__a__t1"] }),
+ ),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![
+ MockStreamEvent::tool_call("call-a", "mcp__a__t1", serde_json::json!({})),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![
+ MockStreamEvent::tool_call(
+ "call-load-b",
+ "load_tools",
+ serde_json::json!({ "names": ["mcp__b__t2"] }),
+ ),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![
+ MockStreamEvent::tool_call("call-b", "mcp__b__t2", serde_json::json!({})),
+ MockStreamEvent::final_response_with_default_usage(),
+ ],
+ vec![MockStreamEvent::final_response_with_default_usage()],
+ ]);
+
+ let toolset: Arc<dyn AiToolSet<()> + Send + Sync> = Arc::new(FakeCombined::new());
+ let mut session = util::session(toolset, Arc::new(()), model).await;
+ let result = util::drive(&mut session, "use both integrations one after another").await;
+
+ assert!(
+ result.error.is_none(),
+ "stream ended with error: {:?}",
+ result.error
+ );
+ expect_json_ok(&result, "mcp__a__t1");
+ expect_json_ok(&result, "mcp__b__t2");
+}
diff --git a/rust/cloud-storage/agent/src/test/test_hook.rs b/rust/cloud-storage/agent/src/test/test_hook.rs
index 3109ac51a8..2b2d7e5326 100644
--- a/rust/cloud-storage/agent/src/test/test_hook.rs
+++ b/rust/cloud-storage/agent/src/test/test_hook.rs
@@ -1,6 +1,6 @@
use crate::hook::*;
use ai_toolset::SearchableTool;
-use rig_core::agent::{HookAction, PromptHook};
+use rig_core::agent::{HookAction, InvalidToolCallContext, InvalidToolCallHookAction, PromptHook};
use rig_core::providers::anthropic::completion::CompletionModel as AnthropicModel;
use schemars::Schema;
use std::pin::Pin;
@@ -40,7 +40,8 @@ async fn on_tool_result_drains_buffer_and_registers_loaded_tools() {
let (register, registered) = recording_register();
let routing: ToolRouter = Arc::new(|_| None);
let token = CancellationToken::new();
- let (bridge, _rx) = StreamBridge::channel(routing, buffer.clone(), register, token);
+ let (bridge, _rx) =
+ StreamBridge::channel(routing, buffer.clone(), register, Arc::new(vec![]), token);
let action = <StreamBridge as PromptHook<AnthropicModel>>::on_tool_result(
&bridge,
@@ -72,7 +73,7 @@ async fn on_tool_result_registers_nothing_when_buffer_empty() {
let (register, registered) = recording_register();
let routing: ToolRouter = Arc::new(|_| None);
let token = CancellationToken::new();
- let (bridge, _rx) = StreamBridge::channel(routing, buffer, register, token);
+ let (bridge, _rx) = StreamBridge::channel(routing, buffer, register, Arc::new(vec![]), token);
let _ = <StreamBridge as PromptHook<AnthropicModel>>::on_tool_result(
&bridge,
@@ -86,3 +87,73 @@ async fn on_tool_result_registers_nothing_when_buffer_empty() {
assert!(registered.lock().unwrap().is_empty());
}
+
+/// An [`InvalidToolCallContext`] for a model-emitted call to `tool_name`.
+fn invalid_call(tool_name: &str) -> InvalidToolCallContext {
+ InvalidToolCallContext {
+ tool_name: tool_name.to_string(),
+ tool_call_id: Some("call-1".to_string()),
+ internal_call_id: Some("internal-1".to_string()),
+ args: Some("{}".to_string()),
+ available_tools: vec!["SearchTools".to_string()],
+ allowed_tools: vec!["SearchTools".to_string()],
+ tool_choice: None,
+ chat_history: vec![],
+ is_streaming: true,
+ }
+}
+
+#[tokio::test]
+async fn invalid_call_to_searchable_tool_loads_it_and_retries() {
+ let (register, registered) = recording_register();
+ let routing: ToolRouter = Arc::new(|_| None);
+ let catalog = Arc::new(vec![searchable("mcp__linear__create_issue")]);
+ let (bridge, _rx) = StreamBridge::channel(
+ routing,
+ Arc::new(Mutex::new(Vec::new())),
+ register,
+ catalog,
+ CancellationToken::new(),
+ );
+
+ let action = <StreamBridge as PromptHook<AnthropicModel>>::on_invalid_tool_call(
+ &bridge,
+ &invalid_call("mcp__linear__create_issue"),
+ )
+ .await;
+
+ // The unloaded-but-searchable tool was registered and the turn retries.
+ assert_eq!(&*registered.lock().unwrap(), &["mcp__linear__create_issue"]);
+ let InvalidToolCallHookAction::Retry { feedback } = action else {
+ panic!("expected retry, got {action:?}");
+ };
+ assert!(feedback.contains("mcp__linear__create_issue"));
+}
+
+#[tokio::test]
+async fn invalid_call_to_unknown_tool_retries_with_feedback_without_loading() {
+ let (register, registered) = recording_register();
+ let routing: ToolRouter = Arc::new(|_| None);
+ let catalog = Arc::new(vec![searchable("mcp__linear__create_issue")]);
+ let (bridge, _rx) = StreamBridge::channel(
+ routing,
+ Arc::new(Mutex::new(Vec::new())),
+ register,
+ catalog,
+ CancellationToken::new(),
+ );
+
+ let action = <StreamBridge as PromptHook<AnthropicModel>>::on_invalid_tool_call(
+ &bridge,
+ &invalid_call("mcp__nope__hallucinated"),
+ )
+ .await;
+
+ // Nothing exists to load; the model gets corrective feedback instead of
+ // the stream failing.
+ assert!(registered.lock().unwrap().is_empty());
+ let InvalidToolCallHookAction::Retry { feedback } = action else {
+ panic!("expected retry, got {action:?}");
+ };
+ assert!(feedback.contains("mcp__nope__hallucinated"));
+}
diff --git a/rust/cloud-storage/ai_tools/src/search_tools.rs b/rust/cloud-storage/ai_tools/src/search_tools.rs
index 06af7b941b..89f3951960 100644
--- a/rust/cloud-storage/ai_tools/src/search_tools.rs
+++ b/rust/cloud-storage/ai_tools/src/search_tools.rs
@@ -10,37 +10,62 @@ use crate::ToolServiceContext;
#[cfg(test)]
mod test;
-/// A tool surfaced by [`SearchTools`] or loaded by [`LoadTools`] — just enough
-/// for the model to decide whether to load it and how to call it.
+/// A tool surfaced by [`SearchTools`] / [`LoadTools`] — just enough for the
+/// model to decide how to call it.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ToolMatch {
- /// The exact name to load and then call the tool by.
+ /// The exact name to call the tool by.
pub name: String,
/// What the tool does.
pub description: String,
}
+impl ToolMatch {
+ fn of(tool: &SearchableTool) -> Self {
+ Self {
+ name: tool.name.clone(),
+ description: tool.description.clone(),
+ }
+ }
+}
+
// ---------------------------------------------------------------------------
-// SearchTools — discovery only
+// SearchTools — discovery + auto-loading
// ---------------------------------------------------------------------------
-/// Response from [`SearchTools`]: matching tools (name + description), not yet
-/// loaded.
+/// How many top-ranked matches a single [`SearchTools`] call loads
+/// automatically.
+///
+/// Every loaded tool's schema is advertised on all subsequent requests for the
+/// session, so auto-loading must be bounded — a broad query against a large
+/// integration would otherwise permanently bloat every following request.
+/// Matches past the cap are still returned (as `additional_matches`) and can
+/// be loaded explicitly with [`LoadTools`].
+const MAX_AUTO_LOADED_MATCHES: usize = 8;
+
+/// Response from [`SearchTools`]: ranked matches, split into the top matches
+/// (auto-loaded, callable on the next model turn) and the remainder (loadable
+/// via [`LoadTools`]).
#[derive(Debug, Serialize, JsonSchema)]
pub struct SearchToolsResponse {
- /// Tools matching the query. Call `LoadTools` with the names you want to use.
+ /// Top matches, ranked by relevance. These are loaded: call them by exact
+ /// name on the next step.
pub results: Vec<ToolMatch>,
+ /// Matches past the auto-load cap, ranked. Not callable yet — pass a name
+ /// to `LoadTools` if one of these is the tool you need.
+ pub additional_matches: Vec<ToolMatch>,
}
/// `SearchTools` discovers tools from connected integrations (MCP servers such
-/// as Slack, Gmail, Linear) that are not listed upfront. It only *finds* tools —
-/// returning their names and descriptions — without loading them, so it can
-/// return many candidates cheaply. To actually use a tool, pass its name to
-/// `LoadTools`.
+/// as Slack, Gmail, Linear) that are not listed upfront, and auto-loads the top
+/// matches so they are callable on the next model turn. This keeps the model
+/// from needing a brittle search → load → call three-step protocol: skipping
+/// the load step left the announced tool unadvertised, so the model's intended
+/// call was never dispatched and the turn ended empty.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(
title = "SearchTools",
- description = "Find tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub) by keyword. Returns matching tools' names and descriptions but does NOT load them — pass the names you want to `LoadTools` to make them callable. Searching is cheap, so cast a wide net."
+ description = "Find tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub) by keyword. The top matches are loaded automatically: call them by exact name on your next step. Matches past the auto-load cap come back under `additional_matches` and need `LoadTools` first. Searching is cheap, so cast a wide net."
)]
pub struct SearchTools {
/// Keywords describing the capability you need (matched against tool names
@@ -61,9 +86,11 @@ impl AsyncTool<ToolServiceContext> for SearchTools {
_service_context: ServiceContext<ToolServiceContext>,
request_context: RequestContext,
) -> ToolResult<Self::Output> {
- Ok(SearchToolsResponse {
- results: search(&request_context.searchable_tools, &self.query),
- })
+ Ok(search_and_stage(
+ &request_context.searchable_tools,
+ &self.query,
+ request_context.tool_loader.as_ref(),
+ ))
}
}
@@ -117,15 +144,14 @@ impl AsyncTool<ToolServiceContext> for LoadTools {
// Pure logic (unit-testable without a service context)
// ---------------------------------------------------------------------------
-/// Match `query` against `catalog` and return the matches' name + description,
-/// ranked by relevance. Does not load anything.
+/// Match `query` against `catalog`, ranked by relevance.
///
/// The query is split into whitespace-separated terms; a tool matches if **any**
/// term is a case-insensitive substring of its name or description, ranked by
/// how many distinct terms match (so "github list commits" surfaces the most
-/// relevant tools first). All matches are returned — searching is cheap and
-/// loading is a separate step. An empty query returns the whole catalog.
-fn search(catalog: &[SearchableTool], query: &str) -> Vec<ToolMatch> {
+/// relevant tools first). All matches are returned — the caller decides how
+/// many to load. An empty query returns the whole catalog.
+fn search<'c>(catalog: &'c [SearchableTool], query: &str) -> Vec<&'c SearchableTool> {
let query = query.to_lowercase();
let terms: Vec<&str> = query.split_whitespace().collect();
@@ -146,13 +172,30 @@ fn search(catalog: &[SearchableTool], query: &str) -> Vec<ToolMatch> {
// Highest term-match count first; tie-break by name for stable ordering.
scored.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.name.cmp(&b.1.name)));
- scored
- .into_iter()
- .map(|(_, t)| ToolMatch {
- name: t.name.clone(),
- description: t.description.clone(),
- })
- .collect()
+ scored.into_iter().map(|(_, t)| t).collect()
+}
+
+/// Match `query`, auto-load the top [`MAX_AUTO_LOADED_MATCHES`] matches so they
+/// are advertised on the next model turn, and report the loaded/unloaded split
+/// to the model.
+fn search_and_stage(
+ catalog: &[SearchableTool],
+ query: &str,
+ loader: Option<&ToolLoader>,
+) -> SearchToolsResponse {
+ let matches = search(catalog, query);
+ let (loaded, additional) = matches.split_at(matches.len().min(MAX_AUTO_LOADED_MATCHES));
+
+ if let Some(loader) = loader
+ && !loaded.is_empty()
+ {
+ loader.load(loaded.iter().map(|&tool| tool.clone()).collect());
+ }
+
+ SearchToolsResponse {
+ results: loaded.iter().copied().map(ToolMatch::of).collect(),
+ additional_matches: additional.iter().copied().map(ToolMatch::of).collect(),
+ }
}
/// Look up `names` in `catalog`, hand the found tools to `loader` for loading,
@@ -168,10 +211,7 @@ fn load(
for name in names {
match catalog.iter().find(|t| &t.name == name) {
Some(t) => {
- loaded.push(ToolMatch {
- name: t.name.clone(),
- description: t.description.clone(),
- });
+ loaded.push(ToolMatch::of(t));
to_load.push(t.clone());
}
None => not_found.push(name.clone()),
diff --git a/rust/cloud-storage/ai_tools/src/search_tools/test.rs b/rust/cloud-storage/ai_tools/src/search_tools/test.rs
index 1de07c145f..935a42f124 100644
--- a/rust/cloud-storage/ai_tools/src/search_tools/test.rs
+++ b/rust/cloud-storage/ai_tools/src/search_tools/test.rs
@@ -34,22 +34,28 @@ fn recording_loader() -> (ToolLoader, Arc<Mutex<Vec<String>>>) {
(loader, recorded)
}
-fn names(matches: &[ToolMatch]) -> Vec<&str> {
+fn names<'a>(tools: &[&'a SearchableTool]) -> Vec<&'a str> {
+ tools.iter().map(|t| t.name.as_str()).collect()
+}
+
+fn match_names(matches: &[ToolMatch]) -> Vec<&str> {
matches.iter().map(|m| m.name.as_str()).collect()
}
-// --- search (discovery only, never loads) ---
+// --- search (pure ranking, loads nothing) ---
#[test]
fn search_matches_by_name() {
- let results = search(&catalog(), "linear");
+ let catalog = catalog();
+ let results = search(&catalog, "linear");
assert_eq!(names(&results), vec!["mcp__linear__create_issue"]);
}
#[test]
fn search_matches_by_description_case_insensitive() {
// "EMAIL" matches the Gmail tool's description ("email threads").
- let results = search(&catalog(), "EMAIL");
+ let catalog = catalog();
+ let results = search(&catalog, "EMAIL");
assert_eq!(names(&results), vec!["mcp__gmail__list_threads"]);
}
@@ -67,7 +73,8 @@ fn search_empty_query_returns_all() {
fn search_multi_word_matches_any_term_and_ranks_by_term_count() {
// "slack" + "message" both hit the Slack tool (score 2); "linear" hits the
// Linear tool (score 1); Gmail matches none.
- let results = search(&catalog(), "slack message linear");
+ let catalog = catalog();
+ let results = search(&catalog, "slack message linear");
assert_eq!(
names(&results),
vec!["mcp__slack__send_message", "mcp__linear__create_issue"]
@@ -82,6 +89,75 @@ fn search_is_uncapped() {
assert_eq!(search(&big, "tool").len(), 50);
}
+// --- search_and_stage (auto-loads the top matches) ---
+
+#[test]
+fn search_and_stage_loads_matched_tools() {
+ let (loader, loaded) = recording_loader();
+
+ let response = search_and_stage(&catalog(), "linear gmail", Some(&loader));
+
+ assert_eq!(
+ match_names(&response.results),
+ vec!["mcp__gmail__list_threads", "mcp__linear__create_issue"]
+ );
+ assert!(response.additional_matches.is_empty());
+ assert_eq!(
+ &*loaded.lock().unwrap(),
+ &[
+ "mcp__gmail__list_threads".to_string(),
+ "mcp__linear__create_issue".to_string()
+ ]
+ );
+}
+
+#[test]
+fn search_and_stage_caps_auto_loading_and_reports_the_rest() {
+ let big: Vec<SearchableTool> = (0..MAX_AUTO_LOADED_MATCHES + 3)
+ .map(|i| tool(&format!("mcp__svc__tool_{i:02}"), "a tool"))
+ .collect();
+ let (loader, loaded) = recording_loader();
+
+ let response = search_and_stage(&big, "tool", Some(&loader));
+
+ // Only the top matches (in rank order) are auto-loaded...
+ assert_eq!(response.results.len(), MAX_AUTO_LOADED_MATCHES);
+ let loaded_names = loaded.lock().unwrap();
+ assert_eq!(
+ loaded_names.iter().map(String::as_str).collect::<Vec<_>>(),
+ match_names(&response.results)
+ );
+ // ...and the remainder is reported for explicit loading, nothing dropped.
+ assert_eq!(response.additional_matches.len(), 3);
+ assert_eq!(
+ match_names(&response.additional_matches),
+ vec![
+ "mcp__svc__tool_08",
+ "mcp__svc__tool_09",
+ "mcp__svc__tool_10"
+ ]
+ );
+}
+
+#[test]
+fn search_and_stage_without_loader_still_returns_matches() {
+ let response = search_and_stage(&catalog(), "linear", None);
+ assert_eq!(
+ match_names(&response.results),
+ vec!["mcp__linear__create_issue"]
+ );
+}
+
+#[test]
+fn search_and_stage_response_always_includes_both_fields() {
+ // The generated frontend schema marks both fields required, so the wire
+ // format must include `additional_matches` even when empty.
+ let response = search_and_stage(&catalog(), "linear", None);
+ let json = serde_json::to_value(&response).unwrap();
+ assert!(json.get("results").is_some());
+ assert_eq!(json["additional_matches"], serde_json::json!([]));
+}
+
// --- load (registers named tools via the loader) ---
#[test]
@@ -93,7 +169,10 @@ fn load_loads_named_tools_and_reports_them() {
Some(&loader),
);
- assert_eq!(names(&result.loaded), vec!["mcp__linear__create_issue"]);
+ assert_eq!(
+ match_names(&result.loaded),
+ vec!["mcp__linear__create_issue"]
+ );
assert!(result.not_found.is_empty());
// The found tool was handed to the loader for registration.
assert_eq!(&*loaded.lock().unwrap(), &["mcp__linear__create_issue"]);
@@ -111,7 +190,10 @@ fn load_reports_unknown_names_and_loads_the_rest() {
Some(&loader),
);
- assert_eq!(names(&result.loaded), vec!["mcp__slack__send_message"]);
+ assert_eq!(
+ match_names(&result.loaded),
+ vec!["mcp__slack__send_message"]
+ );
assert_eq!(result.not_found, vec!["mcp__nope__missing".to_string()]);
assert_eq!(&*loaded.lock().unwrap(), &["mcp__slack__send_message"]);
}
@@ -119,6 +201,9 @@ fn load_reports_unknown_names_and_loads_the_rest() {
#[test]
fn load_without_loader_still_reports() {
let result = load(&catalog(), &["mcp__gmail__list_threads".to_string()], None);
- assert_eq!(names(&result.loaded), vec!["mcp__gmail__list_threads"]);
+ assert_eq!(
+ match_names(&result.loaded),
+ vec!["mcp__gmail__list_threads"]
+ );
assert!(result.not_found.is_empty());
}
diff --git a/rust/cloud-storage/prompt/src/connected_toolsets.rs b/rust/cloud-storage/prompt/src/connected_toolsets.rs
index da6d915c21..11fd5bf859 100644
--- a/rust/cloud-storage/prompt/src/connected_toolsets.rs
+++ b/rust/cloud-storage/prompt/src/connected_toolsets.rs
@@ -42,13 +42,13 @@ pub fn render(names: &[String]) -> Option<String> {
Their individual tools are NOT all listed upfront. When a task might \
need a capability from one of these integrations: (1) call \
`SearchTools` with keywords (e.g. \"linear issue\", \"github commits\") \
- to find matching tools by name and description; (2) call `LoadTools` \
- with the names you want to make them callable; (3) call the loaded tool \
- by its name. Searching is cheap — search broadly, then load only what \
- you need. Think about whether a connected integration is relevant \
- before answering from what you already have; e.g. a question about \
- recent work may be answerable from a connected issue tracker or code \
- host even though those tools aren't visible yet.\n"
+ to find matching tools by name and description; (2) the top matches \
+ are loaded automatically — on the next step, call the tool you need \
+ by its exact name. Searching is cheap — search broadly, then call \
+ only what you need. Think about whether a connected \
+ integration is relevant before answering from what you already have; \
+ e.g. a question about recent work may be answerable from a connected \
+ issue tracker or code host even though those tools aren't visible yet.\n"
))
}
@@ -73,6 +73,6 @@ mod tests {
fn instructs_the_model_to_use_tool_search() {
let section = render(&["Slack".to_string()]).unwrap();
assert!(section.contains("SearchTools"));
- assert!(section.contains("LoadTools"));
+ assert!(!section.contains("LoadTools"));
}
}