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.

feat(agent): lazy-load Macro's native tools (#7552)

Wolf Mermelsteineb007a63dc8a
diff --git a/apps/docs/AI/mcp/tools/load-tools.mdx b/apps/docs/AI/mcp/tools/load-tools.mdx
index 24da7403c8..666fa9dfb2 100644
--- a/apps/docs/AI/mcp/tools/load-tools.mdx
+++ b/apps/docs/AI/mcp/tools/load-tools.mdx
@@ -1,15 +1,16 @@
---
title: LoadTools
description: >-
- Load tools by name (from `SearchTools` results) so you can call them.
+ Load tools by name (from the More Macro Tools list in your instructions, or
+ from `SearchTools` results) so you can call them.
---
# LoadTools
-Load tools by name (from `SearchTools` results) so you can call them. After loading, invoke each tool by its name. Only load the tools you actually need.
+Load tools by name (from the More Macro Tools list in your instructions, or from `SearchTools` results) so you can call them. After loading, invoke each tool by its name. Only load the tools you actually need.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
-| `names` | string[] | Yes | Exact tool names to load, taken from SearchTools results. |
+| `names` | string[] | Yes | Exact tool names to load. |
diff --git a/apps/docs/AI/mcp/tools/search-tools.mdx b/apps/docs/AI/mcp/tools/search-tools.mdx
index 2ecccf3486..555228d4a9 100644
--- a/apps/docs/AI/mcp/tools/search-tools.mdx
+++ b/apps/docs/AI/mcp/tools/search-tools.mdx
@@ -1,12 +1,13 @@
---
title: SearchTools
description: >-
- Find tools from connected integrations (e.g.
+ Find tools by keyword: Macro tools whose parameters are not loaded yet, and
+ tools from connected integrations (e.g.
---
# SearchTools
-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.
+Find tools by keyword: Macro tools whose parameters are not loaded yet, and tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub). 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.
## Parameters
diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
index 92e6ecbb7d..5addae1aec 100644
--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
@@ -8516,11 +8516,11 @@ export interface ToolTeamInvite {
role: string;
}
/**
- * Load tools by name (from `SearchTools` results) so you can call them. After loading, invoke each tool by its name. Only load the tools you actually need.
+ * Load tools by name (from the More Macro Tools list in your instructions, or from `SearchTools` results) so you can call them. After loading, invoke each tool by its name. Only load the tools you actually need.
*/
export interface LoadTools {
/**
- * Exact tool names to load, taken from SearchTools results.
+ * Exact tool names to load.
*/
names: string[];
}
@@ -10290,7 +10290,7 @@ export interface SearchSkillsResponse {
results: SkillSearchResult[];
}
/**
- * 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.
+ * Find tools by keyword: Macro tools whose parameters are not loaded yet, and tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub). 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 {
/**
diff --git a/crates/agent/src/agent_loop.rs b/crates/agent/src/agent_loop.rs
index a5fea26bcc..bb0c3e7335 100644
--- a/crates/agent/src/agent_loop.rs
+++ b/crates/agent/src/agent_loop.rs
@@ -11,7 +11,7 @@ use ai_toolset::{RequestContext, SearchableTool, ToolLoader, ToolSet as AiToolSe
use ai_usage::{UsageContext, UsageRecorder};
use genai_telemetry::ContentPolicy;
use rig_agent::tool::server::{ToolServer, ToolServerHandle};
-use rig_core::message::Message;
+use rig_core::message::{AssistantContent, Message};
use std::future::Future;
use std::pin::Pin;
use std::sync::{Arc, Mutex, RwLock};
@@ -481,6 +481,14 @@ impl Session {
)));
};
+ // A session lives for one turn, so whatever the conversation loaded
+ // before is gone. Reload what it called, in the order it first did,
+ // rather than have the model reload each tool every turn.
+ let called = called_catalog_tools(history, &self.request_context.searchable_tools);
+ if !called.is_empty() {
+ (self.bridge_inputs.register_loaded)(called).await;
+ }
+
let stream = self
.agent
.run_stream(
@@ -504,3 +512,26 @@ impl Session {
&self.history
}
}
+
+/// The catalog tools `history` called, in the order of their first call.
+fn called_catalog_tools(history: &[Message], catalog: &[SearchableTool]) -> Vec<SearchableTool> {
+ let mut called: Vec<SearchableTool> = Vec::new();
+ for message in history {
+ let Message::Assistant { content, .. } = message else {
+ continue;
+ };
+ for content in content.iter() {
+ let AssistantContent::ToolCall(call) = content else {
+ continue;
+ };
+ let name = &call.function.name;
+ if called.iter().any(|tool| &tool.name == name) {
+ continue;
+ }
+ if let Some(tool) = catalog.iter().find(|tool| &tool.name == name) {
+ called.push(tool.clone());
+ }
+ }
+ }
+ called
+}
diff --git a/crates/agent/src/hook.rs b/crates/agent/src/hook.rs
index 68cb08d9a4..fc19d6acc8 100644
--- a/crates/agent/src/hook.rs
+++ b/crates/agent/src/hook.rs
@@ -223,7 +223,8 @@ impl StreamBridge {
);
Some(InvalidToolCallAction::retry(format!(
"The tool `{tool_name}` exists but was not loaded when you called it. \
- It is loaded now — call it again with the same arguments."
+ It is loaded now and its parameters are in your tool list: call it \
+ again, checking your arguments against them."
)))
}
None => Some(InvalidToolCallAction::retry(format!(
diff --git a/crates/agent/src/test/agent_loop/test_tool_search.rs b/crates/agent/src/test/agent_loop/test_tool_search.rs
index 3ddfdb1558..16c6880b49 100644
--- a/crates/agent/src/test/agent_loop/test_tool_search.rs
+++ b/crates/agent/src/test/agent_loop/test_tool_search.rs
@@ -344,3 +344,48 @@ async fn mcp_calls_from_two_providers_loaded_sequentially() {
expect_json_ok(&result, "mcp__a__t1");
expect_json_ok(&result, "mcp__b__t2");
}
+
+/// Sessions are rebuilt every turn, so a tool loaded on an earlier turn would
+/// be gone on the next, and the model would pay a reload round trip each time.
+/// A catalog tool the history already called is loaded before the first
+/// request instead; one the history never called stays out.
+#[tokio::test]
+async fn a_tool_called_earlier_in_the_conversation_is_loaded_upfront() {
+ use rig_core::OneOrMany;
+ use rig_core::message::{AssistantContent, Message};
+
+ let model = MockCompletionModel::from_stream_turns([vec![
+ MockStreamEvent::text("done"),
+ 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.clone()).await;
+
+ let stream = session
+ .send_message(vec![
+ Message::user("use integration a"),
+ Message::Assistant {
+ id: None,
+ content: OneOrMany::one(AssistantContent::tool_call(
+ "call-a",
+ "mcp__a__t1",
+ serde_json::json!({}),
+ )),
+ },
+ Message::tool_result("call-a", "{\"ok\":\"mcp__a__t1\"}"),
+ Message::user("again"),
+ ])
+ .await
+ .expect("send_message should start the stream");
+ let result = util::collect(stream).await;
+ assert!(result.error.is_none(), "{:?}", result.error);
+
+ let requests = model.requests();
+ let advertised: Vec<&str> = requests[0]
+ .tools
+ .iter()
+ .map(|tool| tool.name.as_str())
+ .collect();
+ assert!(advertised.contains(&"mcp__a__t1"), "{advertised:?}");
+ assert!(!advertised.contains(&"mcp__b__t2"), "{advertised:?}");
+}
diff --git a/crates/agent_inmem/src/rig_engine.rs b/crates/agent_inmem/src/rig_engine.rs
index 5e13ded792..b8a115ee67 100644
--- a/crates/agent_inmem/src/rig_engine.rs
+++ b/crates/agent_inmem/src/rig_engine.rs
@@ -25,7 +25,7 @@ use std::sync::Arc;
use agent::{AgentError, AgentLoop, StreamPart};
use ai_tools::user_tool_review::user_tool_finisher;
-use ai_tools::{AiHost, ToolServiceContext, ToolSetWithPrompt, tools_for};
+use ai_tools::{AiHost, DeferredToolSet, ToolServiceContext, ToolSetWithPrompt, tools_for};
use ai_toolset::{AsyncToolCollection, ToolSet as AiToolSet};
use axum::extract::FromRef;
use futures::StreamExt as _;
@@ -294,6 +294,9 @@ async fn drive_turn(
Some(mcp) => Arc::new(mcp_select::CombinedToolSet::new(toolset, mcp)),
None => toolset,
};
+ // Most of Macro's tools go out by name only; the model loads the rest.
+ let toolset: Arc<dyn AiToolSet<_> + Send + Sync> =
+ Arc::new(DeferredToolSet::new(toolset, tools.deferred));
let toolset: Arc<dyn AiToolSet<_> + Send + Sync> = Arc::new(GatedToolSet {
tools: toolset,
gate,
@@ -388,6 +391,7 @@ async fn fetch_user_memory(
let tools = ToolSetWithPrompt {
toolset: tools.toolset,
prompt: tools.prompt,
+ deferred: tools.deferred,
};
let memory_service =
MemoryServiceImpl::new(PgMemoryRepo::new(db.clone()), tool_context.clone(), tools);
diff --git a/crates/ai_tools/src/deferred.rs b/crates/ai_tools/src/deferred.rs
new file mode 100644
index 0000000000..f494c7e29a
--- /dev/null
+++ b/crates/ai_tools/src/deferred.rs
@@ -0,0 +1,94 @@
+//! Deferring tools: keeping their schemas out of every request.
+//!
+//! A deferred tool stays callable, but only its name and description are
+//! offered upfront, in [`ToolSet::searchable_catalog`]. The agent loop's tool
+//! search (`LoadTools`, `SearchTools`, or a call to an unloaded tool) registers
+//! its schema once the model asks for it.
+
+#[cfg(test)]
+mod test;
+
+use std::sync::Arc;
+
+use ai_toolset::{
+ AsyncToolCollection, RequestContext, RequestSchema, SearchableTool, ToolCallFuture, ToolInfo,
+ ToolSet,
+};
+
+/// Catalog entries for every tool in `tools` except `eager`.
+pub fn deferred_tools<Context>(
+ tools: &AsyncToolCollection<Context>,
+ eager: &[&str],
+) -> Arc<[SearchableTool]> {
+ tools
+ .tools
+ .values()
+ .filter(|tool| !eager.contains(&tool.name.as_str()))
+ .map(|tool| SearchableTool {
+ name: tool.name.clone(),
+ description: tool.description.clone(),
+ schema: tool.input_schema.clone().into(),
+ })
+ .collect()
+}
+
+/// `tools` with `deferred` taken out of every request and offered in the
+/// catalog instead, ahead of whatever `tools` already catalogs.
+pub struct DeferredToolSet<Context> {
+ tools: Arc<dyn ToolSet<Context> + Send + Sync>,
+ deferred: Arc<[SearchableTool]>,
+}
+
+impl<Context> DeferredToolSet<Context> {
+ /// Defer `deferred` from `tools`.
+ pub fn new(
+ tools: Arc<dyn ToolSet<Context> + Send + Sync>,
+ deferred: Arc<[SearchableTool]>,
+ ) -> Self {
+ Self { tools, deferred }
+ }
+
+ fn is_deferred(&self, name: &str) -> bool {
+ self.deferred.iter().any(|tool| tool.name == name)
+ }
+}
+
+impl<Context> ToolSet<Context> for DeferredToolSet<Context>
+where
+ Context: Send + Sync + 'static,
+{
+ fn dispatch_tool_call<'a>(
+ &'a self,
+ context: Context,
+ request_context: RequestContext,
+ tool_name: &'a str,
+ json: &'a serde_json::Value,
+ ) -> ToolCallFuture<'a> {
+ self.tools
+ .dispatch_tool_call(context, request_context, tool_name, json)
+ }
+
+ fn request_schemas(&self) -> Option<Vec<RequestSchema>> {
+ let schemas: Vec<RequestSchema> = self
+ .tools
+ .request_schemas()?
+ .into_iter()
+ .filter(|schema| !self.is_deferred(&schema.name))
+ .collect();
+ (!schemas.is_empty()).then_some(schemas)
+ }
+
+ fn searchable_catalog(&self) -> Vec<SearchableTool> {
+ let mut catalog = self.deferred.to_vec();
+ catalog.extend(self.tools.searchable_catalog());
+ catalog
+ }
+
+ fn searchable_toolset_names(&self) -> Vec<String> {
+ self.tools.searchable_toolset_names()
+ }
+
+ fn routing_description<'a>(&'a self, tool_name: &'a str) -> Option<ToolInfo> {
+ self.tools.routing_description(tool_name)
+ }
+}
diff --git a/crates/ai_tools/src/deferred/test.rs b/crates/ai_tools/src/deferred/test.rs
new file mode 100644
index 0000000000..daea8ebaa6
--- /dev/null
+++ b/crates/ai_tools/src/deferred/test.rs
@@ -0,0 +1,162 @@
+use super::*;
+use ai_toolset::{AsyncTool, ServiceContext, ToolAnnotated, ToolAnnotations, ToolResult};
+use macro_user_id::user_id::MacroUserIdStr;
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+#[derive(JsonSchema, Deserialize)]
+#[schemars(title = "ReadThing", description = "Read a thing.")]
+struct ReadThing {
+ #[allow(dead_code)]
+ id: String,
+}
+
+impl ToolAnnotated for ReadThing {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read thing");
+}
+
+#[async_trait::async_trait]
+impl AsyncTool<()> for ReadThing {
+ type Output = String;
+ async fn call(&self, _: ServiceContext<()>, _: RequestContext) -> ToolResult<String> {
+ Ok("read".to_string())
+ }
+}
+
+#[derive(JsonSchema, Deserialize)]
+#[schemars(
+ title = "EditDeck",
+ description = "Edit a slide deck. Applies a batch of operations."
+)]
+struct EditDeck {
+ #[allow(dead_code)]
+ operations: Vec<String>,
+}
+
+impl ToolAnnotated for EditDeck {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Edit deck");
+}
+
+#[async_trait::async_trait]
+impl AsyncTool<()> for EditDeck {
+ type Output = String;
+ async fn call(&self, _: ServiceContext<()>, _: RequestContext) -> ToolResult<String> {
+ Ok("edited".to_string())
+ }
+}
+
+/// An MCP toolset whose one tool is already searchable.
+struct OneMcpTool;
+
+impl ToolSet<()> for OneMcpTool {
+ fn dispatch_tool_call<'a>(
+ &'a self,
+ _: (),
+ _: RequestContext,
+ tool_name: &'a str,
+ _: &'a serde_json::Value,
+ ) -> ToolCallFuture<'a> {
+ Box::pin(async move { Err(ai_toolset::ToolSetError::NotFound(tool_name.to_owned())) })
+ }
+
+ fn request_schemas(&self) -> Option<Vec<RequestSchema>> {
+ None
+ }
+
+ fn searchable_catalog(&self) -> Vec<SearchableTool> {
+ vec![SearchableTool {
+ name: "mcp__linear__create_issue".to_string(),
+ description: "Create a Linear issue.".to_string(),
+ schema: schemars::Schema::default(),
+ }]
+ }
+}
+
+fn read_and_edit() -> AsyncToolCollection<()> {
+ AsyncToolCollection::<()>::new()
+ .add_tool::<ReadThing, ()>()
+ .add_tool::<EditDeck, ()>()
+}
+
+#[test]
+fn deferred_tools_are_every_tool_but_the_eager_ones() {
+ let deferred = deferred_tools(&read_and_edit(), &["ReadThing"]);
+
+ assert_eq!(deferred.len(), 1);
+ assert_eq!(deferred[0].name, "EditDeck");
+ assert_eq!(
+ deferred[0].description,
+ "Edit a slide deck. Applies a batch of operations."
+ );
+ assert!(
+ deferred[0].schema.as_object().unwrap()["properties"]
+ .as_object()
+ .unwrap()
+ .contains_key("operations"),
+ "the catalog carries the schema to register on load"
+ );
+}
+
+#[test]
+fn deferred_tools_move_from_the_request_to_the_catalog() {
+ let tools = read_and_edit();
+ let deferred = deferred_tools(&tools, &["ReadThing"]);
+ let tools = DeferredToolSet::new(Arc::new(tools), deferred);
+
+ let sent: Vec<String> = tools
+ .request_schemas()
+ .unwrap_or_default()
+ .into_iter()
+ .map(|schema| schema.name)
+ .collect();
+ let catalog: Vec<String> = tools
+ .searchable_catalog()
+ .into_iter()
+ .map(|tool| tool.name)
+ .collect();
+
+ assert_eq!(sent, vec!["ReadThing".to_string()]);
+ assert_eq!(catalog, vec!["EditDeck".to_string()]);
+}
+
+#[test]
+fn deferred_tools_come_before_the_inner_catalog() {
+ let deferred = deferred_tools(&read_and_edit(), &[]);
+ let tools = DeferredToolSet::new(Arc::new(OneMcpTool), deferred);
+
+ let catalog: Vec<String> = tools
+ .searchable_catalog()
+ .into_iter()
+ .map(|tool| tool.name)
+ .collect();
+
+ assert_eq!(
+ catalog,
+ vec![
+ "EditDeck".to_string(),
+ "ReadThing".to_string(),
+ "mcp__linear__create_issue".to_string()
+ ]
+ );
+}
+
+#[tokio::test]
+async fn deferred_tools_stay_callable() {
+ let tools = read_and_edit();
+ let deferred = deferred_tools(&tools, &[]);
+ let tools = DeferredToolSet::new(Arc::new(tools), deferred);
+ let user = MacroUserIdStr::try_from_email("[email protected]").unwrap();
+
+ let result = tools
+ .try_tool_call(
+ (),
+ RequestContext::new(user),
+ "EditDeck",
+ &serde_json::json!({ "operations": [] }),
+ )
+ .await
+ .expect("dispatched")
+ .expect("ran");
+
+ assert_eq!(result, serde_json::json!("edited"));
+}
diff --git a/crates/ai_tools/src/lib.rs b/crates/ai_tools/src/lib.rs
index 7bb92f8969..a6096ba759 100644
--- a/crates/ai_tools/src/lib.rs
+++ b/crates/ai_tools/src/lib.rs
@@ -10,6 +10,7 @@ mod test;
pub mod ai_operations;
mod build_context;
+mod deferred;
mod display_results;
mod import_channels;
mod mcp_app_catalog;
@@ -56,6 +57,7 @@ pub use build_context::{
build_anthropic_tool_context, build_image_generator_from_env,
build_tool_service_context_from_env,
};
+pub use deferred::{DeferredToolSet, deferred_tools};
pub use mcp_app_catalog::{PipedreamMcpAppCatalog, pipedream_client_from_env};
pub use search::search_toolset;
pub use tool_context::{
@@ -112,6 +114,9 @@ pub fn database_read_only_tools() -> AiToolSet {
pub struct ToolSetWithPrompt {
pub toolset: Arc<AiToolSet>,
pub prompt: Box<dyn std::fmt::Display + Send + Sync>,
+ /// The tools a [`DeferredToolSet`] keeps out of every request; the prompt
+ /// lists them. Empty on hosts that send every schema.
+ pub deferred: Arc<[ai_toolset::SearchableTool]>,
}
impl ToolSchemaGenerator for ToolSetWithPrompt {
@@ -182,6 +187,38 @@ pub enum AiHost {
Mcp,
}
+/// The tools whose schemas go out with every request on hosts with tool
+/// search: the ones most turns use. Every other tool is deferred (see
+/// [`DeferredToolSet`]), listed by name and summary in the prompt and loaded
+/// with `LoadTools` when needed.
+pub const EAGER_TOOLS: &[&str] = &[
+ "BashCodeExecution",
+ "ContentSearch",
+ "CreateDocument",
+ "DisplayResults",
+ "EditDocument",
+ "GetThread",
+ "ListEntities",
+ "ListSkills",
+ "LoadTools",
+ "NameSearch",
+ "ReadChannelMessageContext",
+ "ReadChannelMessages",
+ "ReadChannelThread",
+ "ReadChat",
+ "ReadContent",
+ "ReadMetadata",
+ "ReadSkill",
+ "SearchSkills",
+ "SearchTools",
+ "SelfKnowledge",
+ "SendChannelMessage",
+ "Subagent",
+ "TextEditorCodeExecution",
+ "WebFetch",
+ "WebSearch",
+];
+
/// Assemble the toolset and tool-use prompt for a host. These are actually
/// sent to the AI provider.
pub fn tools_for(host: AiHost) -> ToolSetWithPrompt {
@@ -213,6 +250,13 @@ pub fn tools_for(host: AiHost) -> ToolSetWithPrompt {
}
AiHost::ChannelBot | AiHost::Mcp => toolset,
};
+ // External MCP clients have no `LoadTools`, so they get every schema.
+ let deferred = match host {
+ AiHost::Chat | AiHost::AgentSession | AiHost::ChannelBot => {
+ deferred_tools(&toolset, EAGER_TOOLS)
+ }
+ AiHost::Mcp => Arc::from([]),
+ };
let prompt: Box<dyn std::fmt::Display + Send + Sync> = match host {
AiHost::Chat => Box::new(prompt::TOOL_USE_PROMPT.compose(&prompt::coding_agents::PROMPT)),
AiHost::AgentSession => {
@@ -222,9 +266,19 @@ pub fn tools_for(host: AiHost) -> ToolSetWithPrompt {
Box::new(prompt::DIRECT_TOOL_USE_PROMPT.compose(&prompt::coding_agents::PROMPT))
}
};
+ let catalog: Vec<(&str, &str)> = deferred
+ .iter()
+ .map(|tool| (tool.name.as_str(), tool.description.as_str()))
+ .collect();
+ let prompt: Box<dyn std::fmt::Display + Send + Sync> =
+ match prompt::deferred_tools::render(&catalog) {
+ Some(section) => Box::new(format!("{prompt}{section}")),
+ None => prompt,
+ };
ToolSetWithPrompt {
toolset: Arc::new(toolset),
prompt,
+ deferred,
}
}
@@ -243,5 +297,6 @@ pub fn no_tools() -> ToolSetWithPrompt {
ToolSetWithPrompt {
prompt: Box::new(&prompt::BASE_PROMPT),
toolset: Arc::new(AsyncToolCollection::new()),
+ deferred: Arc::from([]),
}
}
diff --git a/crates/ai_tools/src/search_tools.rs b/crates/ai_tools/src/search_tools.rs
index 376fc5da29..2c436c76e9 100644
--- a/crates/ai_tools/src/search_tools.rs
+++ b/crates/ai_tools/src/search_tools.rs
@@ -66,7 +66,7 @@ pub struct SearchToolsResponse {
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(
title = "SearchTools",
- 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."
+ description = "Find tools by keyword: Macro tools whose parameters are not loaded yet, and tools from connected integrations (e.g. Slack, Gmail, Linear, GitHub). 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
@@ -119,11 +119,11 @@ pub struct LoadToolsResponse {
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(
title = "LoadTools",
- description = "Load tools by name (from `SearchTools` results) so you can call them. After loading, invoke each tool by its name. Only load the tools you actually need."
+ description = "Load tools by name (from the More Macro Tools list in your instructions, or from `SearchTools` results) so you can call them. After loading, invoke each tool by its name. Only load the tools you actually need."
)]
pub struct LoadTools {
/// Exact tool names to load, as returned by `SearchTools`.
- #[schemars(description = "Exact tool names to load, taken from SearchTools results.")]
+ #[schemars(description = "Exact tool names to load.")]
pub names: Vec<String>,
}
diff --git a/crates/ai_tools/src/test.rs b/crates/ai_tools/src/test.rs
index 9f94aa1af6..a41246293c 100644
--- a/crates/ai_tools/src/test.rs
+++ b/crates/ai_tools/src/test.rs
@@ -335,3 +335,62 @@ fn every_host_exposes_skill_discovery_and_reading() {
);
}
}
+
+#[test]
+fn hosts_with_tool_search_defer_all_but_the_core_tools() {
+ for host in [AiHost::Chat, AiHost::AgentSession, AiHost::ChannelBot] {
+ let tools = tools_for(host);
+ let lazy = DeferredToolSet::new(tools.toolset.clone(), tools.deferred.clone());
+ let sent: Vec<String> = lazy
+ .request_schemas()
+ .unwrap_or_default()
+ .into_iter()
+ .map(|schema| schema.name)
+ .collect();
+ let catalog: Vec<String> = lazy
+ .searchable_catalog()
+ .into_iter()
+ .map(|tool| tool.name)
+ .collect();
+ let prompt = tools.prompt.to_string();
+
+ for name in ["ReadContent", "ContentSearch", "LoadTools", "SearchTools"] {
+ assert!(sent.contains(&name.to_string()), "{host:?} sends {name}");
+ }
+ for name in ["EditPresentation", "EditSpreadsheet", "QueryDatabase"] {
+ assert!(!sent.contains(&name.to_string()), "{host:?} defers {name}");
+ assert!(
+ catalog.contains(&name.to_string()),
+ "{host:?} catalogs {name}"
+ );
+ assert!(
+ prompt.contains(&format!("\n- {name}: ")),
+ "{host:?} lists {name} in the prompt"
+ );
+ }
+ assert_eq!(
+ sent.len() + catalog.len(),
+ tools.toolset.tools.len(),
+ "{host:?}: every tool is either sent or catalogued"
+ );
+ }
+}
+
+#[test]
+fn the_mcp_host_defers_nothing() {
+ let tools = tools_for(AiHost::Mcp);
+
+ assert!(tools.deferred.is_empty());
+ assert!(!tools.prompt.to_string().contains("LoadTools"));
+}
+
+#[test]
+fn every_eager_tool_exists() {
+ let tools = tools_for(AiHost::Chat);
+ for name in EAGER_TOOLS {
+ assert!(
+ tools.toolset.tools.contains_key(*name),
+ "{name} is not a tool"
+ );
+ }
+}
diff --git a/crates/memory/src/domain/service.rs b/crates/memory/src/domain/service.rs
index 7d567ad1f1..5be103c192 100644
--- a/crates/memory/src/domain/service.rs
+++ b/crates/memory/src/domain/service.rs
@@ -125,10 +125,15 @@ where
let repo = self.memory_repo.clone();
let tool_context = self.tool_context.clone();
let toolset = self.tools.toolset.clone();
+ let deferred = self.tools.deferred.clone();
let prompt: Box<dyn std::fmt::Display + Send + Sync> =
Box::new(self.tools.prompt.to_string());
tokio::spawn(async move {
- let tools = ToolSetWithPrompt { toolset, prompt };
+ let tools = ToolSetWithPrompt {
+ toolset,
+ prompt,
+ deferred,
+ };
let svc = MemoryServiceImpl::new(repo, tool_context, tools);
match svc.generate_memory(user.clone(), previous_memory).await {
Ok(_) => tracing::info!(%user, "memory generated"),
@@ -166,8 +171,9 @@ where
let agent_loop =
AgentLoop::new(self.tool_context.recorder.clone()).with_model(GENERATION_MODEL);
- let toolset: Arc<dyn ai_toolset::ToolSet<_> + Send + Sync> =
- self.tools.toolset.clone() as _;
+ let toolset: Arc<dyn ai_toolset::ToolSet<_> + Send + Sync> = Arc::new(
+ ai_tools::DeferredToolSet::new(self.tools.toolset.clone(), self.tools.deferred.clone()),
+ );
let usage_ctx = ai_usage::UsageContext::new(ai_usage::AiFeature::Memory, user.clone());
// Carry the feature on the context so tool-spawned subagents attribute to it.
let mut tool_context = self.tool_context.clone();
diff --git a/crates/prompt/src/deferred_tools.rs b/crates/prompt/src/deferred_tools.rs
new file mode 100644
index 0000000000..c434b2ab37
--- /dev/null
+++ b/crates/prompt/src/deferred_tools.rs
@@ -0,0 +1,52 @@
+//! Lists Macro's deferred tools so the model knows they exist.
+//!
+//! Most of Macro's tools are not sent with every request: their parameter
+//! schemas are large and most turns never use them. The model still needs to
+//! know they exist, so this section names each one with a one-line summary,
+//! and the model loads the ones it needs with `LoadTools`.
+//!
+//! The deferred set depends on the host's toolset, so this section is rendered
+//! by [`render`] rather than declared as a `'static` prompt.
+
+#[cfg(test)]
+mod test;
+
+static TITLE: &str = "More Macro Tools";
+
+/// The most of a description a summary keeps when it has no sentence break.
+const MAX_SUMMARY_CHARS: usize = 200;
+
+/// Renders the section listing `tools` as `(name, description)` pairs, each
+/// description cut to its first sentence. `None` when nothing is deferred.
+pub fn render(tools: &[(&str, &str)]) -> Option<String> {
+ if tools.is_empty() {
+ return None;
+ }
+ let list = tools
+ .iter()
+ .map(|(name, description)| format!("- {name}: {}", summary(description)))
+ .collect::<Vec<_>>()
+ .join("\n");
+ Some(format!(
+ "# {TITLE}\n\
+ These tools are available too, but their parameters are not loaded \
+ yet. To use one, call `LoadTools` with its exact name (load several \
+ at once if the task needs them), then call it on your next step. \
+ `SearchTools` also finds them by keyword. Once you have called a \
+ tool, it stays loaded for the rest of the conversation.\n\
+ {list}\n"
+ ))
+}
+
+/// The first sentence of `description`, on one line.
+fn summary(description: &str) -> String {
+ let line = description.split_whitespace().collect::<Vec<_>>().join(" ");
+ let sentence = match line.find(". ") {
+ Some(end) => &line[..=end],
+ None => line.as_str(),
+ };
+ match sentence.char_indices().nth(MAX_SUMMARY_CHARS) {
+ Some((cut, _)) => format!("{}…", &sentence[..cut]),
+ None => sentence.to_string(),
+ }
+}
diff --git a/crates/prompt/src/deferred_tools/test.rs b/crates/prompt/src/deferred_tools/test.rs
new file mode 100644
index 0000000000..03519f1dfc
--- /dev/null
+++ b/crates/prompt/src/deferred_tools/test.rs
@@ -0,0 +1,44 @@
+use super::*;
+
+#[test]
+fn nothing_deferred_omits_the_section() {
+ assert_eq!(render(&[]), None);
+}
+
+#[test]
+fn lists_each_tool_by_name_with_its_first_sentence() {
+ let section = render(&[
+ (
+ "EditPresentation",
+ "Edit a PowerPoint (.pptx) presentation: an ordered batch of operations. \
+ To make a new deck from an existing one, pass saveAs.",
+ ),
+ ("ListReminders", "List the user's reminders"),
+ ])
+ .unwrap();
+
+ assert_eq!(
+ section,
+ "# More Macro Tools\n\
+ These tools are available too, but their parameters are not loaded yet. \
+ To use one, call `LoadTools` with its exact name (load several at once if \
+ the task needs them), then call it on your next step. `SearchTools` also \
+ finds them by keyword. Once you have called a tool, it stays loaded for \
+ the rest of the conversation.\n\
+ - EditPresentation: Edit a PowerPoint (.pptx) presentation: an ordered batch of operations.\n\
+ - ListReminders: List the user's reminders\n"
+ );
+}
+
+#[test]
+fn a_long_unbroken_description_is_cut() {
+ let description = "word ".repeat(100);
+ let section = render(&[("Long", &description)]).unwrap();
+ let line = section.lines().last().unwrap();
+
+ assert_eq!(
+ line.chars().count(),
+ "- Long: ".len() + MAX_SUMMARY_CHARS + 1
+ );
+ assert!(line.ends_with('…'));
+}
diff --git a/crates/prompt/src/lib.rs b/crates/prompt/src/lib.rs
index 1497f7562f..2540d8935b 100644
--- a/crates/prompt/src/lib.rs
+++ b/crates/prompt/src/lib.rs
@@ -13,6 +13,7 @@ pub mod citations;
pub mod coding_agents;
pub mod connected_toolsets;
pub mod databases;
+pub mod deferred_tools;
pub mod do_not;
pub mod document_content_links;
pub mod email;