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(ai_toolset): require MCP tool annotations on every tool (#5685)

Eric Hayesabd8e21458a6
diff --git a/crates/agent/src/test/agent_loop/test_cooperative_cancellation.rs b/crates/agent/src/test/agent_loop/test_cooperative_cancellation.rs
index bd9de01d83..ae9cd0ce76 100644
--- a/crates/agent/src/test/agent_loop/test_cooperative_cancellation.rs
+++ b/crates/agent/src/test/agent_loop/test_cooperative_cancellation.rs
@@ -10,6 +10,7 @@
use super::util;
use crate::stream::ToolResponse;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use rig_core::test_utils::{MockCompletionModel, MockStreamEvent};
use schemars::JsonSchema;
@@ -37,6 +38,10 @@ struct TestCtx {
)]
struct InfiniteTool {}
+impl ToolAnnotated for InfiniteTool {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Infinite");
+}
+
#[async_trait]
impl AsyncTool<TestCtx> for InfiniteTool {
type Output = serde_json::Value;
diff --git a/crates/agent/src/test/agent_loop/test_eager_tools.rs b/crates/agent/src/test/agent_loop/test_eager_tools.rs
index af0e2b93b9..2495d5a159 100644
--- a/crates/agent/src/test/agent_loop/test_eager_tools.rs
+++ b/crates/agent/src/test/agent_loop/test_eager_tools.rs
@@ -9,6 +9,7 @@
use super::util;
use crate::stream::{StreamPart, ToolResponse};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use rig_core::message::Message;
use rig_core::test_utils::{MockCompletionModel, MockStreamEvent};
@@ -28,6 +29,10 @@ const GRACE: Duration = Duration::from_millis(500);
#[schemars(title = "never_tool", description = "Never returns.")]
struct NeverTool {}
+impl ToolAnnotated for NeverTool {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Never");
+}
+
#[async_trait]
impl AsyncTool<()> for NeverTool {
type Output = serde_json::Value;
@@ -93,6 +98,10 @@ struct Gate {
#[schemars(title = "gated_tool", description = "Returns only once released.")]
struct GatedTool {}
+impl ToolAnnotated for GatedTool {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Gated");
+}
+
#[async_trait]
impl AsyncTool<Gate> for GatedTool {
type Output = serde_json::Value;
@@ -178,6 +187,10 @@ struct EchoTool {
value: String,
}
+impl ToolAnnotated for EchoTool {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Echo");
+}
+
#[async_trait]
impl AsyncTool<()> for EchoTool {
type Output = serde_json::Value;
diff --git a/crates/agent/src/test/agent_loop/test_tool.rs b/crates/agent/src/test/agent_loop/test_tool.rs
index 9141f07bf8..328830f6a9 100644
--- a/crates/agent/src/test/agent_loop/test_tool.rs
+++ b/crates/agent/src/test/agent_loop/test_tool.rs
@@ -5,6 +5,7 @@ use crate::stream::ToolResponse;
use ai_toolset::{
AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolCallError, ToolResult,
};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use rig_core::test_utils::{MockCompletionModel, MockStreamEvent};
use schemars::JsonSchema;
@@ -18,6 +19,10 @@ struct EchoTool {
value: String,
}
+impl ToolAnnotated for EchoTool {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Echo");
+}
+
#[async_trait]
impl AsyncTool<()> for EchoTool {
type Output = serde_json::Value;
@@ -36,6 +41,10 @@ impl AsyncTool<()> for EchoTool {
#[schemars(title = "boom_tool", description = "Always fails.")]
struct BoomTool {}
+impl ToolAnnotated for BoomTool {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Boom");
+}
+
#[async_trait]
impl AsyncTool<()> for BoomTool {
type Output = serde_json::Value;
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 629a775ea6..ab68910144 100644
--- a/crates/agent/src/test/agent_loop/test_tool_search.rs
+++ b/crates/agent/src/test/agent_loop/test_tool_search.rs
@@ -11,6 +11,7 @@ use ai_toolset::{
AsyncTool, AsyncToolCollection, RequestContext, RequestSchema, SearchableTool, ServiceContext,
ToolResult, ToolSet as AiToolSet, ToolSetError,
};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use rig_core::test_utils::{MockCompletionModel, MockStreamEvent};
use schemars::{JsonSchema, Schema};
@@ -28,6 +29,10 @@ use std::sync::Arc;
)]
struct SearchToolsTest {}
+impl ToolAnnotated for SearchToolsTest {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Search tools");
+}
+
#[async_trait]
impl AsyncTool<()> for SearchToolsTest {
type Output = serde_json::Value;
@@ -55,6 +60,10 @@ struct LoadToolsTest {
names: Vec<String>,
}
+impl ToolAnnotated for LoadToolsTest {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Load tools");
+}
+
#[async_trait]
impl AsyncTool<()> for LoadToolsTest {
type Output = serde_json::Value;
diff --git a/crates/agent/src/test/agent_loop/util.rs b/crates/agent/src/test/agent_loop/util.rs
index 1c6c476597..3a0e710ae4 100644
--- a/crates/agent/src/test/agent_loop/util.rs
+++ b/crates/agent/src/test/agent_loop/util.rs
@@ -11,7 +11,7 @@ use crate::AgentLoop;
use crate::Session;
use crate::error::AgentError;
use crate::stream::{ChatCompletionStream, StreamPart, ToolCall, ToolResponse};
-use ai_toolset::{AsyncTool, AsyncToolCollection, ToolSet as AiToolSet};
+use ai_toolset::{AsyncTool, AsyncToolCollection, ToolAnnotated, ToolSet as AiToolSet};
use ai_usage::{AiFeature, UsageContext, UsageEvent, UsageRecorder};
use futures::StreamExt;
use macro_user_id::user_id::MacroUserIdStr;
@@ -51,7 +51,13 @@ pub(crate) fn usage_ctx() -> UsageContext {
pub(crate) fn single_tool_set<T, C>() -> Arc<dyn AiToolSet<C> + Send + Sync>
where
C: Clone + Send + Sync + 'static,
- T: JsonSchema + AsyncTool<C> + for<'de> serde::Deserialize<'de> + Send + Sync + 'static,
+ T: JsonSchema
+ + AsyncTool<C>
+ + ToolAnnotated
+ + for<'de> serde::Deserialize<'de>
+ + Send
+ + Sync
+ + 'static,
T::Output: Serialize + JsonSchema + 'static,
{
Arc::new(AsyncToolCollection::<C>::new().add_tool::<T, C>())
diff --git a/crates/ai_tools/src/display_results.rs b/crates/ai_tools/src/display_results.rs
index 763ab089f0..82fa6220ae 100644
--- a/crates/ai_tools/src/display_results.rs
+++ b/crates/ai_tools/src/display_results.rs
@@ -1,4 +1,5 @@
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
@@ -33,6 +34,11 @@ pub struct DisplayResults {
pub view: serde_json::Value,
}
+impl ToolAnnotated for DisplayResults {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::read_only("Show results").without_idempotent();
+}
+
#[async_trait]
impl AsyncTool<ToolServiceContext> for DisplayResults {
type Output = DisplayResultsResponse;
diff --git a/crates/ai_tools/src/search/search_service/content.rs b/crates/ai_tools/src/search/search_service/content.rs
index 9b35b2d8b8..be6e9d33c3 100644
--- a/crates/ai_tools/src/search/search_service/content.rs
+++ b/crates/ai_tools/src/search/search_service/content.rs
@@ -4,6 +4,7 @@ use super::types::{
tag_filter_mode,
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use email::domain::ports::EmailService;
use item_filters::{EmailFilters, EntityFilters};
@@ -65,6 +66,10 @@ Ignored unless tags is set.")]
pub tags_match: TagMatch,
}
+impl ToolAnnotated for ContentSearch {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Search content");
+}
+
#[async_trait]
impl AsyncTool<SearchToolContext> for ContentSearch {
type Output = SearchToolResponse;
diff --git a/crates/ai_tools/src/search/search_service/name.rs b/crates/ai_tools/src/search/search_service/name.rs
index 76adcb752a..bec2753973 100644
--- a/crates/ai_tools/src/search/search_service/name.rs
+++ b/crates/ai_tools/src/search/search_service/name.rs
@@ -4,6 +4,7 @@ use super::types::{
tag_filter_mode,
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use email::domain::ports::EmailService;
use item_filters::{EmailFilters, EntityFilters};
@@ -67,6 +68,10 @@ Ignored unless tags is set.")]
pub tags_match: TagMatch,
}
+impl ToolAnnotated for NameSearch {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Search by name");
+}
+
#[async_trait]
impl AsyncTool<SearchToolContext> for NameSearch {
type Output = SearchToolResponse;
diff --git a/crates/ai_tools/src/search_tools.rs b/crates/ai_tools/src/search_tools.rs
index 89f3951960..376fc5da29 100644
--- a/crates/ai_tools/src/search_tools.rs
+++ b/crates/ai_tools/src/search_tools.rs
@@ -1,6 +1,7 @@
use ai_toolset::{
AsyncTool, RequestContext, SearchableTool, ServiceContext, ToolLoader, ToolResult,
};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
@@ -76,6 +77,10 @@ pub struct SearchTools {
pub query: String,
}
+impl ToolAnnotated for SearchTools {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Search tools");
+}
+
#[async_trait]
impl AsyncTool<ToolServiceContext> for SearchTools {
type Output = SearchToolsResponse;
@@ -122,6 +127,10 @@ pub struct LoadTools {
pub names: Vec<String>,
}
+impl ToolAnnotated for LoadTools {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Load tools");
+}
+
#[async_trait]
impl AsyncTool<ToolServiceContext> for LoadTools {
type Output = LoadToolsResponse;
diff --git a/crates/ai_tools/src/self_knowledge.rs b/crates/ai_tools/src/self_knowledge.rs
index dc24bd8081..d2cd9b6545 100644
--- a/crates/ai_tools/src/self_knowledge.rs
+++ b/crates/ai_tools/src/self_knowledge.rs
@@ -1,4 +1,5 @@
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
@@ -118,6 +119,10 @@ pub struct SelfKnowledgeResponse {
pub about: String,
}
+impl ToolAnnotated for SelfKnowledge {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("About Macro");
+}
+
#[async_trait]
impl AsyncTool<ToolServiceContext> for SelfKnowledge {
type Output = SelfKnowledgeResponse;
diff --git a/crates/ai_tools/src/subagent.rs b/crates/ai_tools/src/subagent.rs
index 4fade6467b..24139360d3 100644
--- a/crates/ai_tools/src/subagent.rs
+++ b/crates/ai_tools/src/subagent.rs
@@ -1,5 +1,6 @@
use agent::PredefinedModel;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
@@ -28,6 +29,11 @@ pub struct Subagent {
pub task: String,
}
+impl ToolAnnotated for Subagent {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::destructive("Delegate to subagent").with_open_world();
+}
+
#[async_trait]
impl AsyncTool<ToolServiceContext> for Subagent {
type Output = SubagentResponse;
diff --git a/crates/ai_toolset/src/annotations.rs b/crates/ai_toolset/src/annotations.rs
new file mode 100644
index 0000000000..4a11633d19
--- /dev/null
+++ b/crates/ai_toolset/src/annotations.rs
@@ -0,0 +1,150 @@
+//! MCP-facing metadata describing what a tool is called and what it does to
+//! the user's workspace.
+//!
+//! Every tool added to a toolset must declare these via [`ToolAnnotated`].
+//! The trait has no blanket implementation and the const has no default, so a
+//! tool that omits them fails to compile at the point it is added — an
+//! unannotated tool cannot reach an MCP client.
+//!
+//! These are deliberately protocol-agnostic. The MCP transport maps
+//! [`ToolKind`] onto the wire-level `readOnlyHint` / `destructiveHint` pair;
+//! the AI provider codepaths ignore annotations entirely.
+
+/// How a tool affects the user's workspace.
+///
+/// This models the MCP `readOnlyHint` / `destructiveHint` pair as a single
+/// choice, because only three of their four combinations are meaningful:
+/// a tool cannot be both read-only and destructive.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ToolKind {
+ /// The tool does not modify anything. Clients may run it without asking
+ /// the user for per-call confirmation.
+ ReadOnly,
+ /// The tool creates or adds, but never overwrites or removes existing
+ /// data.
+ Additive,
+ /// The tool overwrites or removes existing data. Clients always prompt
+ /// before running it.
+ Destructive,
+}
+
+impl ToolKind {
+ /// The MCP `readOnlyHint` value for this kind.
+ pub const fn read_only_hint(self) -> bool {
+ matches!(self, Self::ReadOnly)
+ }
+
+ /// The MCP `destructiveHint` value for this kind.
+ ///
+ /// Only meaningful when [`Self::read_only_hint`] is `false`.
+ pub const fn destructive_hint(self) -> bool {
+ matches!(self, Self::Destructive)
+ }
+}
+
+/// MCP-facing metadata for a single tool.
+///
+/// Build these with [`ToolAnnotations::read_only`],
+/// [`ToolAnnotations::additive`], or [`ToolAnnotations::destructive`], then
+/// adjust the optional hints with the `with_*` methods where the default is
+/// wrong.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ToolAnnotations {
+ /// Human-readable display name shown to the user, distinct from the
+ /// tool's machine name.
+ ///
+ /// The machine name (`SendChannelMessage`) comes from the schemars
+ /// `title`; this is the name a person reads in a permission prompt
+ /// (`Send channel message`).
+ pub title: &'static str,
+ /// What the tool does to the workspace.
+ pub kind: ToolKind,
+ /// Whether the tool reaches systems outside Macro. Maps to the MCP
+ /// `openWorldHint`.
+ pub open_world: bool,
+ /// Whether repeating the call with the same arguments has no further
+ /// effect. Maps to the MCP `idempotentHint`.
+ pub idempotent: bool,
+}
+
+impl ToolAnnotations {
+ /// Annotates a tool that modifies nothing.
+ ///
+ /// Defaults to idempotent, since repeating a read changes nothing.
+ pub const fn read_only(title: &'static str) -> Self {
+ Self {
+ title,
+ kind: ToolKind::ReadOnly,
+ open_world: false,
+ idempotent: true,
+ }
+ }
+
+ /// Annotates a tool that creates or adds without overwriting or removing.
+ pub const fn additive(title: &'static str) -> Self {
+ Self {
+ title,
+ kind: ToolKind::Additive,
+ open_world: false,
+ idempotent: false,
+ }
+ }
+
+ /// Annotates a tool that overwrites or removes existing data.
+ pub const fn destructive(title: &'static str) -> Self {
+ Self {
+ title,
+ kind: ToolKind::Destructive,
+ open_world: false,
+ idempotent: false,
+ }
+ }
+
+ /// Marks the tool as reaching systems outside Macro.
+ pub const fn with_open_world(mut self) -> Self {
+ self.open_world = true;
+ self
+ }
+
+ /// Marks the tool as safe to repeat with the same arguments.
+ pub const fn with_idempotent(mut self) -> Self {
+ self.idempotent = true;
+ self
+ }
+
+ /// Marks the tool as unsafe to repeat with the same arguments.
+ pub const fn without_idempotent(mut self) -> Self {
+ self.idempotent = false;
+ self
+ }
+}
+
+/// Declares a tool's MCP annotations.
+///
+/// Required by [`AsyncToolCollection::add_tool`] and
+/// [`AsyncToolCollection::add_user_tool`]. There is no blanket implementation
+/// and no default value, so adding a tool that has not declared its
+/// annotations is a compile error.
+///
+/// [`AsyncToolCollection::add_tool`]: crate::AsyncToolCollection::add_tool
+/// [`AsyncToolCollection::add_user_tool`]: crate::AsyncToolCollection::add_user_tool
+///
+/// # Example
+///
+/// ```
+/// use ai_toolset::{ToolAnnotated, ToolAnnotations};
+///
+/// struct RenameDocument { id: String, name: String }
+///
+/// impl ToolAnnotated for RenameDocument {
+/// const ANNOTATIONS: ToolAnnotations =
+/// ToolAnnotations::destructive("Rename document");
+/// }
+/// ```
+pub trait ToolAnnotated {
+ /// This tool's display title and workspace effect.
+ const ANNOTATIONS: ToolAnnotations;
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/ai_toolset/src/annotations/test.rs b/crates/ai_toolset/src/annotations/test.rs
new file mode 100644
index 0000000000..4e06f45927
--- /dev/null
+++ b/crates/ai_toolset/src/annotations/test.rs
@@ -0,0 +1,74 @@
+use super::*;
+
+#[test]
+fn read_only_maps_to_read_only_hint_only() {
+ let annotations = ToolAnnotations::read_only("Read document");
+ assert!(annotations.kind.read_only_hint());
+ assert!(!annotations.kind.destructive_hint());
+}
+
+#[test]
+fn additive_sets_neither_hint() {
+ let annotations = ToolAnnotations::additive("Create document");
+ assert!(!annotations.kind.read_only_hint());
+ assert!(!annotations.kind.destructive_hint());
+}
+
+#[test]
+fn destructive_sets_destructive_hint_only() {
+ let annotations = ToolAnnotations::destructive("Delete tag");
+ assert!(!annotations.kind.read_only_hint());
+ assert!(annotations.kind.destructive_hint());
+}
+
+#[test]
+fn no_kind_sets_both_hints() {
+ // The pair readOnlyHint == destructiveHint == true is meaningless in MCP.
+ // Modelling the two booleans as one enum makes it unrepresentable.
+ for kind in [
+ ToolKind::ReadOnly,
+ ToolKind::Additive,
+ ToolKind::Destructive,
+ ] {
+ assert!(
+ !(kind.read_only_hint() && kind.destructive_hint()),
+ "{kind:?} claims to be both read-only and destructive"
+ );
+ }
+}
+
+#[test]
+fn reads_default_to_idempotent_and_closed_world() {
+ let annotations = ToolAnnotations::read_only("Search content");
+ assert!(annotations.idempotent);
+ assert!(!annotations.open_world);
+}
+
+#[test]
+fn writes_default_to_non_idempotent() {
+ assert!(!ToolAnnotations::additive("Create project").idempotent);
+ assert!(!ToolAnnotations::destructive("Edit document").idempotent);
+}
+
+#[test]
+fn builders_override_defaults() {
+ let annotations = ToolAnnotations::additive("Import Notion page")
+ .with_open_world()
+ .with_idempotent();
+ assert!(annotations.open_world);
+ assert!(annotations.idempotent);
+
+ let annotations = ToolAnnotations::read_only("Fetch a web page").without_idempotent();
+ assert!(!annotations.idempotent);
+}
+
+#[test]
+fn annotations_are_const_constructible() {
+ // The whole enforcement story depends on these being usable as an
+ // associated const, so pin that they evaluate at compile time.
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::destructive("Send channel message").with_open_world();
+ assert_eq!(ANNOTATIONS.title, "Send channel message");
+ assert_eq!(ANNOTATIONS.kind, ToolKind::Destructive);
+ assert!(ANNOTATIONS.open_world);
+}
diff --git a/crates/ai_toolset/src/lib.rs b/crates/ai_toolset/src/lib.rs
index eacce58098..5602b11277 100644
--- a/crates/ai_toolset/src/lib.rs
+++ b/crates/ai_toolset/src/lib.rs
@@ -19,7 +19,10 @@
//! ensures compile-time safety when extracting tool-specific contexts.
//!
//! ```
-//! use ai_toolset::{AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolResult};
+//! use ai_toolset::{
+//! AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolAnnotated,
+//! ToolAnnotations, ToolResult,
+//! };
//! use axum_macros::FromRef;
//! use schemars::JsonSchema;
//! use serde::{Deserialize, Serialize};
@@ -48,6 +51,10 @@
//! #[schemars(title = "ReadDocument", description = "Reads a document by ID")]
//! struct ReadDocumentTool { document_id: String }
//!
+//! impl ToolAnnotated for ReadDocumentTool {
+//! const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read document");
+//! }
+//!
//! #[async_trait::async_trait]
//! impl AsyncTool<Arc<dyn DocumentApi>> for ReadDocumentTool {
//! type Output = serde_json::Value;
@@ -62,6 +69,10 @@
//! #[schemars(title = "UpdateProperty", description = "Updates a property value")]
//! struct UpdatePropertyTool { property_id: String, value: String }
//!
+//! impl ToolAnnotated for UpdatePropertyTool {
+//! const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Update property");
+//! }
+//!
//! #[async_trait::async_trait]
//! impl AsyncTool<Arc<dyn PropertyApi>> for UpdatePropertyTool {
//! type Output = serde_json::Value;
@@ -84,7 +95,10 @@
//! derivable from the parent context via `FromRef`.
//!
//! ```
-//! use ai_toolset::{AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolResult};
+//! use ai_toolset::{
+//! AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolAnnotated,
+//! ToolAnnotations, ToolResult,
+//! };
//! use axum_macros::FromRef;
//! use schemars::JsonSchema;
//! use serde::{Deserialize, Serialize};
@@ -108,6 +122,10 @@
//! #[schemars(title = "SubTool", description = "A tool using SubContext")]
//! struct SubTool { value: String }
//!
+//! impl ToolAnnotated for SubTool {
+//! const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Sub tool");
+//! }
+//!
//! #[async_trait::async_trait]
//! impl AsyncTool<SubContext> for SubTool {
//! type Output = serde_json::Value;
@@ -129,12 +147,14 @@
#![deny(missing_docs)]
+mod annotations;
mod context;
pub mod schema;
mod tool;
pub mod tool_search;
mod toolset;
+pub use annotations::{ToolAnnotated, ToolAnnotations, ToolKind};
pub use context::{RequestContext, ServiceContext};
pub use tool::{AsyncTool, NoContext, ToolCallError, ToolResult};
pub use tool_search::{SearchableTool, ToolLoader};
diff --git a/crates/ai_toolset/src/toolset/tool_object/object.rs b/crates/ai_toolset/src/toolset/tool_object/object.rs
index 383b5d6873..fa7c4be158 100644
--- a/crates/ai_toolset/src/toolset/tool_object/object.rs
+++ b/crates/ai_toolset/src/toolset/tool_object/object.rs
@@ -1,3 +1,4 @@
+use crate::annotations::ToolAnnotations;
use schemars::SchemaGenerator;
use serde_json::Map;
use serde_json::Value;
@@ -17,6 +18,9 @@ pub struct ToolObject<T> {
pub description: String,
/// The unique name of the tool.
pub name: String,
+ /// MCP-facing display title and workspace effect, declared by the tool
+ /// via [`ToolAnnotated`](crate::ToolAnnotated).
+ pub annotations: ToolAnnotations,
/// The deserializer function for converting JSON to the tool type.
pub deserializer: T,
/// Registers this tool's input/output types with a shared generator
diff --git a/crates/ai_toolset/src/toolset/tool_object/tool_async.rs b/crates/ai_toolset/src/toolset/tool_object/tool_async.rs
index dac2bbefd2..e51bb7dab7 100644
--- a/crates/ai_toolset/src/toolset/tool_object/tool_async.rs
+++ b/crates/ai_toolset/src/toolset/tool_object/tool_async.rs
@@ -1,4 +1,5 @@
use super::object::{SchemaRegistrar, ToolObject};
+use crate::annotations::ToolAnnotated;
use crate::schema::{ValidatedSchema, ValidationError, generate_validated_input_schema};
use crate::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
use async_trait::async_trait;
@@ -147,6 +148,7 @@ where
ToolContext: FromRef<ToolSetContext> + Send + Sync + 'static,
T: JsonSchema
+ AsyncTool<ToolContext, Output = O>
+ + ToolAnnotated
+ for<'de> Deserialize<'de>
+ 'static
+ Send
@@ -183,6 +185,7 @@ where
name,
input_schema: input_schema_json,
description,
+ annotations: T::ANNOTATIONS,
deserializer,
schema_registrar,
})
@@ -201,7 +204,9 @@ where
/// # Example
///
/// ```
- /// use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolResult};
+ /// use ai_toolset::{
+ /// AsyncTool, RequestContext, ServiceContext, ToolAnnotated, ToolAnnotations, ToolResult,
+ /// };
/// use ai_toolset::tool_object::AsyncToolObject;
/// use axum_macros::FromRef;
/// use schemars::JsonSchema;
@@ -226,6 +231,10 @@ where
/// #[schemars(title = "MyTool", description = "Example tool")]
/// struct MyTool { input: String }
///
+ /// impl ToolAnnotated for MyTool {
+ /// const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("My tool");
+ /// }
+ ///
/// #[async_trait::async_trait]
/// impl AsyncTool<SubContext> for MyTool {
/// type Output = serde_json::Value;
@@ -264,6 +273,7 @@ where
name: self.name,
input_schema: self.input_schema,
description: self.description,
+ annotations: self.annotations,
deserializer: new_deserializer,
schema_registrar: self.schema_registrar,
}
diff --git a/crates/ai_toolset/src/toolset/tool_object/user_tool.rs b/crates/ai_toolset/src/toolset/tool_object/user_tool.rs
index 3a56c44b64..003c37139c 100644
--- a/crates/ai_toolset/src/toolset/tool_object/user_tool.rs
+++ b/crates/ai_toolset/src/toolset/tool_object/user_tool.rs
@@ -3,6 +3,7 @@
//! A user execues a tool T by posting to /tools/call/{:tool_id} with body appliction/json T
//! User tools are _opaque_ to the tool loop. IE it will call the `call` method like it would
//! for any other tool, but the call method won't trigger execution
+use crate::annotations::{ToolAnnotated, ToolAnnotations};
use crate::{AsyncTool, ToolResult};
use crate::{RequestContext, ServiceContext};
use async_trait::async_trait;
@@ -24,6 +25,12 @@ impl<T: JsonSchema> JsonSchema for UserTool<T> {
}
}
+/// A user tool carries the wrapped tool's annotations: deferring execution to
+/// the user changes when the effect happens, not what the effect is.
+impl<T: ToolAnnotated> ToolAnnotated for UserTool<T> {
+ const ANNOTATIONS: ToolAnnotations = T::ANNOTATIONS;
+}
+
/// User tools are pending until a user executes them
#[derive(Serialize, Deserialize, JsonSchema, ToSchema, Debug, Clone, PartialEq)]
pub enum UserToolResponse<T> {
diff --git a/crates/ai_toolset/src/toolset/types.rs b/crates/ai_toolset/src/toolset/types.rs
index b93e48138c..cecddecb8c 100644
--- a/crates/ai_toolset/src/toolset/types.rs
+++ b/crates/ai_toolset/src/toolset/types.rs
@@ -1,6 +1,7 @@
//! types
use super::tool_object::{AsyncToolObject, UserTool, UserToolResponse};
use crate::RequestContext;
+use crate::annotations::ToolAnnotated;
use crate::schema::ValidationError;
use crate::{AsyncTool, ToolResult};
use axum::extract::FromRef;
@@ -137,7 +138,13 @@ where
pub fn add_tool<T, ToolContext>(mut self) -> Self
where
ToolContext: Sync + Send + FromRef<ToolSetContext> + 'static,
- T: JsonSchema + AsyncTool<ToolContext> + for<'de> Deserialize<'de> + 'static + Send + Sync,
+ T: JsonSchema
+ + AsyncTool<ToolContext>
+ + ToolAnnotated
+ + for<'de> Deserialize<'de>
+ + 'static
+ + Send
+ + Sync,
T::Output: Serialize + JsonSchema + 'static,
{
let tool_object = AsyncToolObject::try_from_tool::<T, ToolContext, T::Output>()
@@ -158,7 +165,13 @@ where
pub fn add_user_tool<T, ToolContext>(mut self) -> Self
where
ToolContext: Sync + Send + FromRef<ToolSetContext> + 'static,
- T: JsonSchema + AsyncTool<ToolContext> + for<'de> Deserialize<'de> + 'static + Send + Sync,
+ T: JsonSchema
+ + AsyncTool<ToolContext>
+ + ToolAnnotated
+ + for<'de> Deserialize<'de>
+ + 'static
+ + Send
+ + Sync,
T::Output: Serialize + JsonSchema + 'static,
{
let tool_object = AsyncToolObject::try_from_tool::<T, ToolContext, T::Output>()
@@ -249,7 +262,10 @@ where
/// # Example
///
/// ```
- /// use ai_toolset::{AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolResult};
+ /// use ai_toolset::{
+ /// AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolAnnotated,
+ /// ToolAnnotations, ToolResult,
+ /// };
/// use axum_macros::FromRef;
/// use schemars::JsonSchema;
/// use serde::{Deserialize, Serialize};
@@ -273,6 +289,10 @@ where
/// #[schemars(title = "SubTool", description = "A tool using SubContext")]
/// struct SubTool { value: String }
///
+ /// impl ToolAnnotated for SubTool {
+ /// const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Sub tool");
+ /// }
+ ///
/// #[async_trait::async_trait]
/// impl AsyncTool<SubContext> for SubTool {
/// type Output = serde_json::Value;
diff --git a/crates/anthropic/src/toolset/bash_code_execution.rs b/crates/anthropic/src/toolset/bash_code_execution.rs
index d807814c74..5acf1a392e 100644
--- a/crates/anthropic/src/toolset/bash_code_execution.rs
+++ b/crates/anthropic/src/toolset/bash_code_execution.rs
@@ -3,6 +3,7 @@ use crate::types::request::CODE_EXECUTION_TOOL;
use crate::types::response::ResponseContentKind;
use crate::types::response::code_execution::BashCodeExecutionResponse;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::Deserialize;
@@ -18,6 +19,11 @@ pub struct BashCodeExecution {
pub input: String,
}
+impl ToolAnnotated for BashCodeExecution {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::destructive("Run bash command").with_open_world();
+}
+
#[async_trait]
impl AsyncTool<AnthropicToolContext> for BashCodeExecution {
type Output = BashCodeExecutionResponse;
diff --git a/crates/anthropic/src/toolset/text_editor_code_execution.rs b/crates/anthropic/src/toolset/text_editor_code_execution.rs
index 65563ce600..1e910bba79 100644
--- a/crates/anthropic/src/toolset/text_editor_code_execution.rs
+++ b/crates/anthropic/src/toolset/text_editor_code_execution.rs
@@ -3,6 +3,7 @@ use crate::types::request::CODE_EXECUTION_TOOL;
use crate::types::response::ResponseContentKind;
use crate::types::response::code_execution::TextEditorCodeExecutionResponse;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::Deserialize;
@@ -18,6 +19,11 @@ pub struct TextEditorCodeExecution {
pub input: String,
}
+impl ToolAnnotated for TextEditorCodeExecution {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::destructive("Edit file in sandbox").with_open_world();
+}
+
#[async_trait]
impl AsyncTool<AnthropicToolContext> for TextEditorCodeExecution {
type Output = TextEditorCodeExecutionResponse;
diff --git a/crates/anthropic/src/toolset/web_fetch.rs b/crates/anthropic/src/toolset/web_fetch.rs
index d223a0e306..b120315c8b 100644
--- a/crates/anthropic/src/toolset/web_fetch.rs
+++ b/crates/anthropic/src/toolset/web_fetch.rs
@@ -3,6 +3,7 @@ use crate::types::request::WEB_FETCH_TOOL;
use crate::types::response::ResponseContentKind;
use crate::types::response::web_fetch::WebFetchResponse;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::Deserialize;
@@ -18,6 +19,12 @@ pub struct WebFetch {
pub input: String,
}
+impl ToolAnnotated for WebFetch {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Fetch a web page")
+ .with_open_world()
+ .without_idempotent();
+}
+
#[async_trait]
impl AsyncTool<AnthropicToolContext> for WebFetch {
type Output = WebFetchResponse;
diff --git a/crates/anthropic/src/toolset/web_search.rs b/crates/anthropic/src/toolset/web_search.rs
index af4fc44800..252e62bd22 100644
--- a/crates/anthropic/src/toolset/web_search.rs
+++ b/crates/anthropic/src/toolset/web_search.rs
@@ -3,6 +3,7 @@ use crate::types::request::WEB_SEARCH_TOOL;
use crate::types::response::ResponseContentKind;
use crate::types::response::web_search::WebSearchResponse;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::Deserialize;
@@ -18,6 +19,12 @@ pub struct WebSearch {
pub input: String,
}
+impl ToolAnnotated for WebSearch {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Search the web")
+ .with_open_world()
+ .without_idempotent();
+}
+
#[async_trait]
impl AsyncTool<AnthropicToolContext> for WebSearch {
type Output = WebSearchResponse;
diff --git a/crates/call/src/inbound/toolset/read_call_record.rs b/crates/call/src/inbound/toolset/read_call_record.rs
index 2181d379dd..a140ad7550 100644
--- a/crates/call/src/inbound/toolset/read_call_record.rs
+++ b/crates/call/src/inbound/toolset/read_call_record.rs
@@ -2,6 +2,7 @@
use crate::domain::ports::CallService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use entity_access::domain::{
@@ -75,6 +76,10 @@ pub struct ReadCallRecord {
pub call_id: Uuid,
}
+impl ToolAnnotated for ReadCallRecord {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read call transcript");
+}
+
#[async_trait]
impl<CSvc, ESvc> AsyncTool<CallToolContext<CSvc, ESvc>> for ReadCallRecord
where
diff --git a/crates/channels/src/inbound/toolset/read_channel_message_context.rs b/crates/channels/src/inbound/toolset/read_channel_message_context.rs
index f6b991f316..47ce587a85 100644
--- a/crates/channels/src/inbound/toolset/read_channel_message_context.rs
+++ b/crates/channels/src/inbound/toolset/read_channel_message_context.rs
@@ -8,6 +8,7 @@ use super::types::{
use crate::domain::models::ChannelMessageKind;
use crate::domain::ports::ChannelService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use schemars::JsonSchema;
@@ -108,6 +109,10 @@ pub struct ReadChannelMessageContextResponse {
pub omissions: Vec<ToolOmission>,
}
+impl ToolAnnotated for ReadChannelMessageContext {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read message context");
+}
+
#[async_trait]
impl<Svc, AccessSvc> AsyncTool<ChannelToolContext<Svc, AccessSvc>> for ReadChannelMessageContext
where
diff --git a/crates/channels/src/inbound/toolset/read_channel_messages.rs b/crates/channels/src/inbound/toolset/read_channel_messages.rs
index 9e651986b9..9ebe52a249 100644
--- a/crates/channels/src/inbound/toolset/read_channel_messages.rs
+++ b/crates/channels/src/inbound/toolset/read_channel_messages.rs
@@ -8,6 +8,7 @@ use super::types::{
use crate::domain::models::{ChannelMessageFilters, MessagePageDirection};
use crate::domain::ports::{ChannelMessagesQueryResult, ChannelService};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use entity_access::domain::ports::EntityAccessService;
@@ -160,6 +161,10 @@ pub struct ReadChannelMessagesResponse {
pub omissions: Vec<ToolOmission>,
}
+impl ToolAnnotated for ReadChannelMessages {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read channel messages");
+}
+
#[async_trait]
impl<Svc, AccessSvc> AsyncTool<ChannelToolContext<Svc, AccessSvc>> for ReadChannelMessages
where
diff --git a/crates/channels/src/inbound/toolset/read_channel_thread.rs b/crates/channels/src/inbound/toolset/read_channel_thread.rs
index 892b8fde7e..3dd4652737 100644
--- a/crates/channels/src/inbound/toolset/read_channel_thread.rs
+++ b/crates/channels/src/inbound/toolset/read_channel_thread.rs
@@ -7,6 +7,7 @@ use super::types::{
};
use crate::domain::ports::ChannelService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use entity_access::domain::ports::EntityAccessService;
@@ -114,6 +115,10 @@ pub struct ReadChannelThreadResponse {
pub omissions: Vec<ToolOmission>,
}
+impl ToolAnnotated for ReadChannelThread {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read channel thread");
+}
+
#[async_trait]
impl<Svc, AccessSvc> AsyncTool<ChannelToolContext<Svc, AccessSvc>> for ReadChannelThread
where
diff --git a/crates/channels/src/inbound/toolset/send_channel_message.rs b/crates/channels/src/inbound/toolset/send_channel_message.rs
index 9dfffc1b32..b0a9c6f3b0 100644
--- a/crates/channels/src/inbound/toolset/send_channel_message.rs
+++ b/crates/channels/src/inbound/toolset/send_channel_message.rs
@@ -1,4 +1,5 @@
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
@@ -34,6 +35,10 @@ pub struct SendChannelMessageResponse {
pub message_id: String,
}
+impl ToolAnnotated for SendChannelMessage {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Send channel message");
+}
+
#[async_trait]
impl<Svc, AccessSvc> AsyncTool<ChannelToolContext<Svc, AccessSvc>> for SendChannelMessage
where
diff --git a/crates/chat/src/domain/service/chat/test.rs b/crates/chat/src/domain/service/chat/test.rs
index 2141419ec7..db7d9db9f2 100644
--- a/crates/chat/src/domain/service/chat/test.rs
+++ b/crates/chat/src/domain/service/chat/test.rs
@@ -1,7 +1,9 @@
use std::sync::Mutex;
use agent::types::{AssistantMessagePart, ChatMessageContent};
-use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolResult};
+use ai_toolset::{
+ AsyncTool, RequestContext, ServiceContext, ToolAnnotated, ToolAnnotations, ToolResult,
+};
use attachment::FormattedParts;
use entity_access_management::domain::models::EntityAccessManagementError;
use macro_event_broker::{EventBrokerError, MacroEvent};
@@ -307,6 +309,10 @@ impl MacroEventBroker for RecordingEventBroker {
// -- Test tool --
+impl ToolAnnotated for TestTool {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Test tool");
+}
+
#[derive(serde::Deserialize, schemars::JsonSchema)]
#[schemars(title = "test_tool", description = "A tool used by chat service tests")]
struct TestTool {
diff --git a/crates/chat/src/inbound/toolset/read_chat.rs b/crates/chat/src/inbound/toolset/read_chat.rs
index 5434b59dd9..97a9857312 100644
--- a/crates/chat/src/inbound/toolset/read_chat.rs
+++ b/crates/chat/src/inbound/toolset/read_chat.rs
@@ -2,6 +2,7 @@
use crate::domain::ports::ChatService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::{
models::{EntityType, ViewAccessLevel},
@@ -49,6 +50,10 @@ pub struct ReadChat {
pub chat_id: String,
}
+impl ToolAnnotated for ReadChat {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read chat history");
+}
+
#[async_trait]
impl<CSvc, ESvc> AsyncTool<ChatToolContext<CSvc, ESvc>> for ReadChat
where
diff --git a/crates/crm/src/inbound/toolset/get_company.rs b/crates/crm/src/inbound/toolset/get_company.rs
index 82e87a0917..7d0ed7de8a 100644
--- a/crates/crm/src/inbound/toolset/get_company.rs
+++ b/crates/crm/src/inbound/toolset/get_company.rs
@@ -1,6 +1,7 @@
//! GetCompany tool for reading a single CRM company's details.
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use entity_access::domain::{
@@ -135,6 +136,10 @@ pub struct GetCompany {
pub company_id: Uuid,
}
+impl ToolAnnotated for GetCompany {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read company");
+}
+
#[async_trait]
impl<CSvc, ESvc, PSvc> AsyncTool<CrmToolContext<CSvc, ESvc, PSvc>> for GetCompany
where
diff --git a/crates/crm/src/inbound/toolset/list_companies.rs b/crates/crm/src/inbound/toolset/list_companies.rs
index 03bb28a0c5..2260e18ed3 100644
--- a/crates/crm/src/inbound/toolset/list_companies.rs
+++ b/crates/crm/src/inbound/toolset/list_companies.rs
@@ -1,6 +1,7 @@
//! ListCompanies tool for browsing the caller team's CRM companies.
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use entity_access::domain::{
@@ -108,6 +109,10 @@ pub struct ListCompanies {
pub limit: Option<u16>,
}
+impl ToolAnnotated for ListCompanies {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("List companies");
+}
+
#[async_trait]
impl<CSvc, ESvc, PSvc> AsyncTool<CrmToolContext<CSvc, ESvc, PSvc>> for ListCompanies
where
diff --git a/crates/documents/src/inbound/toolset/create_document.rs b/crates/documents/src/inbound/toolset/create_document.rs
index bafa7ab449..abc77ddd37 100644
--- a/crates/documents/src/inbound/toolset/create_document.rs
+++ b/crates/documents/src/inbound/toolset/create_document.rs
@@ -1,5 +1,6 @@
//! CreateDocument tool for reading document content.
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use std::str::FromStr;
use crate::domain::create::{NewDocumentMetadata, NewPlainTextDocument};
@@ -66,6 +67,10 @@ pub struct CreateDocument {
pub project_id: Option<uuid::Uuid>,
}
+impl ToolAnnotated for CreateDocument {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::additive("Create document");
+}
+
#[async_trait]
impl<DSvc, ESvc, EDSvc> AsyncTool<DocumentToolContext<DSvc, ESvc, EDSvc>> for CreateDocument
where
diff --git a/crates/documents/src/inbound/toolset/edit_document.rs b/crates/documents/src/inbound/toolset/edit_document.rs
index bf8708b57e..229794befb 100644
--- a/crates/documents/src/inbound/toolset/edit_document.rs
+++ b/crates/documents/src/inbound/toolset/edit_document.rs
@@ -5,6 +5,7 @@ use crate::domain::ports::{
DocumentService, create::DocumentCreationService, editing::EditingWorkerService,
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::{
models::{EditAccessLevel, EntityType},
@@ -71,6 +72,10 @@ pub struct EditDocumentResponse {
pub clarification: Option<String>,
}
+impl ToolAnnotated for EditDocument {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Edit document");
+}
+
#[async_trait]
impl<DSvc, ESvc, EDSvc> AsyncTool<DocumentToolContext<DSvc, ESvc, EDSvc>> for EditDocument
where
diff --git a/crates/documents/src/inbound/toolset/read_content.rs b/crates/documents/src/inbound/toolset/read_content.rs
index 2ba08c0c75..c39a5aa303 100644
--- a/crates/documents/src/inbound/toolset/read_content.rs
+++ b/crates/documents/src/inbound/toolset/read_content.rs
@@ -1,5 +1,6 @@
//! ReadContent tool for reading document content.
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use std::str::FromStr;
use crate::domain::{
@@ -89,6 +90,10 @@ pub struct ReadContent {
pub document_id: Uuid,
}
+impl ToolAnnotated for ReadContent {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read document");
+}
+
#[async_trait]
impl<DSvc, ESvc, EDSvc> AsyncTool<DocumentToolContext<DSvc, ESvc, EDSvc>> for ReadContent
where
diff --git a/crates/documents/src/inbound/toolset/read_metadata.rs b/crates/documents/src/inbound/toolset/read_metadata.rs
index c439f618dd..94a19546b9 100644
--- a/crates/documents/src/inbound/toolset/read_metadata.rs
+++ b/crates/documents/src/inbound/toolset/read_metadata.rs
@@ -5,6 +5,7 @@ use crate::domain::ports::{
};
use crate::domain::response::DocumentMetadataWithContent;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::{
models::{AccessLevel, EntityType},
@@ -44,6 +45,10 @@ pub struct ReadMetadata {
pub document_id: Uuid,
}
+impl ToolAnnotated for ReadMetadata {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read document metadata");
+}
+
#[async_trait]
impl<DSvc, ESvc, EDSvc> AsyncTool<DocumentToolContext<DSvc, ESvc, EDSvc>> for ReadMetadata
where
diff --git a/crates/documents/src/inbound/toolset/rename_document.rs b/crates/documents/src/inbound/toolset/rename_document.rs
index 3fdcbb4869..a3254d4271 100644
--- a/crates/documents/src/inbound/toolset/rename_document.rs
+++ b/crates/documents/src/inbound/toolset/rename_document.rs
@@ -5,6 +5,7 @@ use crate::domain::{
ports::{DocumentService, create::DocumentCreationService, editing::EditingWorkerService},
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::{models::EntityType, ports::EntityAccessService};
use models_permissions::share_permission::access_level::EditAccessLevel;
@@ -58,6 +59,10 @@ pub struct RenameDocument {
pub document_name: String,
}
+impl ToolAnnotated for RenameDocument {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Rename document");
+}
+
#[async_trait]
impl<DSvc, ESvc, EDSvc> AsyncTool<DocumentToolContext<DSvc, ESvc, EDSvc>> for RenameDocument
where
diff --git a/crates/email/src/inbound/toolset/get_thread.rs b/crates/email/src/inbound/toolset/get_thread.rs
index b9a9f59849..9ceaffadd9 100644
--- a/crates/email/src/inbound/toolset/get_thread.rs
+++ b/crates/email/src/inbound/toolset/get_thread.rs
@@ -5,6 +5,7 @@ use crate::domain::{
ports::{EmailService, GmailTokenProvider},
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::{
models::{EntityType, ViewAccessLevel},
@@ -107,6 +108,10 @@ pub struct GetThread {
pub limit: Option<i64>,
}
+impl ToolAnnotated for GetThread {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read email thread");
+}
+
#[async_trait]
impl<T, G, E> AsyncTool<EmailToolContext<T, G, E>> for GetThread
where
diff --git a/crates/email/src/inbound/toolset/list_inboxes.rs b/crates/email/src/inbound/toolset/list_inboxes.rs
index 3f4e51f938..ed901980a7 100644
--- a/crates/email/src/inbound/toolset/list_inboxes.rs
+++ b/crates/email/src/inbound/toolset/list_inboxes.rs
@@ -2,6 +2,7 @@
use crate::domain::ports::{EmailService, GmailTokenProvider};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use macro_user_id::user_id::MacroUserIdStr;
@@ -53,6 +54,10 @@ and you do not need this tool. Do not guess inbox addresses — list them here f
)]
pub struct ListInboxes {}
+impl ToolAnnotated for ListInboxes {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("List inboxes");
+}
+
#[async_trait]
impl<T, G, E> AsyncTool<EmailToolContext<T, G, E>> for ListInboxes
where
diff --git a/crates/email/src/inbound/toolset/list_labels.rs b/crates/email/src/inbound/toolset/list_labels.rs
index 8edefc4d10..d8fc2705f4 100644
--- a/crates/email/src/inbound/toolset/list_labels.rs
+++ b/crates/email/src/inbound/toolset/list_labels.rs
@@ -5,6 +5,7 @@ use crate::domain::{
ports::{EmailService, GmailTokenProvider},
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use macro_user_id::user_id::MacroUserIdStr;
@@ -97,6 +98,10 @@ pub struct ListLabels {
pub inbox: Option<String>,
}
+impl ToolAnnotated for ListLabels {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("List Gmail labels");
+}
+
#[async_trait]
impl<T, G, E> AsyncTool<EmailToolContext<T, G, E>> for ListLabels
where
diff --git a/crates/email/src/inbound/toolset/send_email.rs b/crates/email/src/inbound/toolset/send_email.rs
index 1b445a9adb..5c4ab54105 100644
--- a/crates/email/src/inbound/toolset/send_email.rs
+++ b/crates/email/src/inbound/toolset/send_email.rs
@@ -5,6 +5,7 @@ use crate::domain::{
ports::{EmailService, GmailTokenProvider},
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use macro_user_id::user_id::MacroUserIdStr;
@@ -86,6 +87,11 @@ pub enum SendEmailResponse {
UserEdited,
}
+impl ToolAnnotated for SendEmail {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::destructive("Send email").with_open_world();
+}
+
#[async_trait]
impl<T, G, E> AsyncTool<EmailToolContext<T, G, E>> for SendEmail
where
diff --git a/crates/email/src/inbound/toolset/update_thread_labels.rs b/crates/email/src/inbound/toolset/update_thread_labels.rs
index 10852b82dd..e18df56082 100644
--- a/crates/email/src/inbound/toolset/update_thread_labels.rs
+++ b/crates/email/src/inbound/toolset/update_thread_labels.rs
@@ -2,6 +2,7 @@
use crate::domain::ports::{EmailService, GmailTokenProvider};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use macro_user_id::user_id::MacroUserIdStr;
@@ -61,6 +62,10 @@ pub struct UpdateThreadLabelsResponse {
pub summary: String,
}
+impl ToolAnnotated for UpdateThreadLabels {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Update thread labels");
+}
+
#[async_trait]
impl<T, G, E> AsyncTool<EmailToolContext<T, G, E>> for UpdateThreadLabels
where
diff --git a/crates/import/src/inbound/toolset.rs b/crates/import/src/inbound/toolset.rs
index 9268b29925..20ffbdf69e 100644
--- a/crates/import/src/inbound/toolset.rs
+++ b/crates/import/src/inbound/toolset.rs
@@ -20,6 +20,7 @@ use crate::domain::service::{
use ai_toolset::{
AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolCallError, ToolResult,
};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
@@ -253,6 +254,10 @@ pub struct CreateImportEntityResponse {
pub message: String,
}
+impl ToolAnnotated for CreateImportEntity {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::additive("Track import candidate");
+}
+
#[async_trait]
impl<T: ImportStager> AsyncTool<ImportToolContext<T>> for CreateImportEntity {
type Output = CreateImportEntityResponse;
@@ -419,6 +424,11 @@ pub struct ImportNotionPageResponse {
pub message: String,
}
+impl ToolAnnotated for ImportNotionPage {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::additive("Import Notion page").with_open_world();
+}
+
#[async_trait]
impl<T: NotionPageImporter> AsyncTool<ImportToolContext<T>> for ImportNotionPage {
type Output = ImportNotionPageResponse;
@@ -516,6 +526,10 @@ pub struct DeleteImportEntityResponse {
pub message: String,
}
+impl ToolAnnotated for DeleteImportEntity {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Decline import candidate");
+}
+
#[async_trait]
impl<T: ImportStager> AsyncTool<ImportToolContext<T>> for DeleteImportEntity {
type Output = DeleteImportEntityResponse;
@@ -581,6 +595,10 @@ pub struct ListImportEntitiesResponse {
pub entities: Vec<ImportEntityView>,
}
+impl ToolAnnotated for ListImportEntities {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("List import ledger");
+}
+
#[async_trait]
impl<T: ImportStager> AsyncTool<ImportToolContext<T>> for ListImportEntities {
type Output = ListImportEntitiesResponse;
@@ -649,6 +667,10 @@ pub struct FinalizeImportResponse {
pub entity_type: String,
}
+impl ToolAnnotated for FinalizeImport {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::additive("Finalize import");
+}
+
#[async_trait]
impl<T: ImportFinalizer> AsyncTool<ImportToolContext<T>> for FinalizeImport {
type Output = FinalizeImportResponse;
diff --git a/crates/notification/src/inbound/ai_tool/mod.rs b/crates/notification/src/inbound/ai_tool/mod.rs
index a33bfe4228..b5eff91c23 100644
--- a/crates/notification/src/inbound/ai_tool/mod.rs
+++ b/crates/notification/src/inbound/ai_tool/mod.rs
@@ -16,6 +16,7 @@ use crate::domain::{
use ai_toolset::{
AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolCallError, ToolResult,
};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use cowlike::CowLike;
use macro_user_id::user_id::MacroUserIdStr;
@@ -222,6 +223,10 @@ pub struct ListNotificationsResponse {
pub has_more: bool,
}
+impl ToolAnnotated for ListNotifications {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("List notifications");
+}
+
#[async_trait]
impl<T> AsyncTool<NotificationToolContext<T>> for ListNotifications
where
@@ -301,6 +306,11 @@ pub struct MarkNotificationsSeen {
pub notification_ids: Vec<Uuid>,
}
+impl ToolAnnotated for MarkNotificationsSeen {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::additive("Mark notifications seen").with_idempotent();
+}
+
#[async_trait]
impl<T> AsyncTool<NotificationToolContext<T>> for MarkNotificationsSeen
where
@@ -355,6 +365,11 @@ pub struct MarkNotificationsDone {
pub done: bool,
}
+impl ToolAnnotated for MarkNotificationsDone {
+ const ANNOTATIONS: ToolAnnotations =
+ ToolAnnotations::additive("Mark notifications done").with_idempotent();
+}
+
#[async_trait]
impl<T> AsyncTool<NotificationToolContext<T>> for MarkNotificationsDone
where
diff --git a/crates/projects/src/inbound/toolset/create_project.rs b/crates/projects/src/inbound/toolset/create_project.rs
index e444acc3ff..66ee0f076c 100644
--- a/crates/projects/src/inbound/toolset/create_project.rs
+++ b/crates/projects/src/inbound/toolset/create_project.rs
@@ -1,6 +1,7 @@
//! CreateProject tool for creating projects (folders).
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use anyhow::Context;
use async_trait::async_trait;
use entity_access::domain::models::EditAccessLevel;
@@ -60,6 +61,10 @@ pub struct CreateProject {
pub parent_project_id: Option<uuid::Uuid>,
}
+impl ToolAnnotated for CreateProject {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::additive("Create project");
+}
+
#[async_trait]
impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
for CreateProject
diff --git a/crates/projects/src/inbound/toolset/move_to_project.rs b/crates/projects/src/inbound/toolset/move_to_project.rs
index 6a358d7ac3..40d220365c 100644
--- a/crates/projects/src/inbound/toolset/move_to_project.rs
+++ b/crates/projects/src/inbound/toolset/move_to_project.rs
@@ -1,6 +1,7 @@
//! MoveToProject tool for moving entities into and out of projects (folders).
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::models::EditAccessLevel;
use entity_access::domain::ports::EntityAccessService;
@@ -160,6 +161,10 @@ pub struct MoveToProject {
pub project_id: Option<uuid::Uuid>,
}
+impl ToolAnnotated for MoveToProject {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Move to project");
+}
+
#[async_trait]
impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
for MoveToProject
diff --git a/crates/projects/src/inbound/toolset/read_project.rs b/crates/projects/src/inbound/toolset/read_project.rs
index 4d0a1ec0e2..5f99def498 100644
--- a/crates/projects/src/inbound/toolset/read_project.rs
+++ b/crates/projects/src/inbound/toolset/read_project.rs
@@ -1,6 +1,7 @@
//! ReadProject tool for listing a project's (folder's) contents.
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::models::ViewAccessLevel;
use entity_access::domain::ports::EntityAccessService;
@@ -99,6 +100,10 @@ pub struct ReadProject {
pub project_id: uuid::Uuid,
}
+impl ToolAnnotated for ReadProject {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read project contents");
+}
+
#[async_trait]
impl<PSvc, ESvc, DSvc, CSvc, EmSvc> AsyncTool<ProjectToolContext<PSvc, ESvc, DSvc, CSvc, EmSvc>>
for ReadProject
diff --git a/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rs b/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rs
index 6938d07c40..946bd27eda 100644
--- a/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rs
+++ b/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rs
@@ -4,6 +4,7 @@
use crate::domain::model::{EditReceipt, EntityOptionUpdateOutcome};
use crate::domain::service::PropertiesService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::models::EditAccessLevel;
use entity_access::domain::ports::EntityAccessService;
@@ -93,6 +94,10 @@ fn entity_type_label(entity_type: ToolPropertyTargetEntityType) -> &'static str
}
}
+impl ToolAnnotated for BulkSetEntityPropertyOptions {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Bulk-update properties");
+}
+
#[async_trait]
impl<T, A> AsyncTool<PropertiesToolContext<T, A>> for BulkSetEntityPropertyOptions
where
diff --git a/crates/properties/src/inbound/toolset/create_tag.rs b/crates/properties/src/inbound/toolset/create_tag.rs
index 820f7a9413..80764fa688 100644
--- a/crates/properties/src/inbound/toolset/create_tag.rs
+++ b/crates/properties/src/inbound/toolset/create_tag.rs
@@ -3,6 +3,7 @@
use crate::domain::model::TagScope as DomainTagScope;
use crate::domain::service::PropertiesService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use models_properties::api::{AddPropertyOptionRequest, AddStringOptionRequest};
@@ -61,6 +62,10 @@ pub struct CreateTagResponse {
pub summary: String,
}
+impl ToolAnnotated for CreateTag {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::additive("Create tag");
+}
+
#[async_trait]
impl<T, A> AsyncTool<PropertiesToolContext<T, A>> for CreateTag
where
diff --git a/crates/properties/src/inbound/toolset/delete_tag.rs b/crates/properties/src/inbound/toolset/delete_tag.rs
index eadcfb1aa2..f643e092f5 100644
--- a/crates/properties/src/inbound/toolset/delete_tag.rs
+++ b/crates/properties/src/inbound/toolset/delete_tag.rs
@@ -2,6 +2,7 @@
use crate::domain::service::PropertiesService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use schemars::JsonSchema;
@@ -37,6 +38,10 @@ pub struct DeleteTagResponse {
pub message: String,
}
+impl ToolAnnotated for DeleteTag {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Delete tag");
+}
+
#[async_trait]
impl<T, A> AsyncTool<PropertiesToolContext<T, A>> for DeleteTag
where
diff --git a/crates/properties/src/inbound/toolset/edit_tag.rs b/crates/properties/src/inbound/toolset/edit_tag.rs
index eeb8a5cf82..a467b025aa 100644
--- a/crates/properties/src/inbound/toolset/edit_tag.rs
+++ b/crates/properties/src/inbound/toolset/edit_tag.rs
@@ -2,6 +2,7 @@
use crate::domain::service::PropertiesService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use models_properties::api::UpdatePropertyOptionRequest;
@@ -57,6 +58,10 @@ pub struct EditTagResponse {
pub summary: String,
}
+impl ToolAnnotated for EditTag {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Edit tag");
+}
+
#[async_trait]
impl<T, A> AsyncTool<PropertiesToolContext<T, A>> for EditTag
where
diff --git a/crates/properties/src/inbound/toolset/get_entity_properties.rs b/crates/properties/src/inbound/toolset/get_entity_properties.rs
index f4b034d310..6c52fe8686 100644
--- a/crates/properties/src/inbound/toolset/get_entity_properties.rs
+++ b/crates/properties/src/inbound/toolset/get_entity_properties.rs
@@ -3,6 +3,7 @@
use crate::domain::model::{EntityPropertyInfo, PropertyOptionInfo};
use crate::domain::service::PropertiesService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::models::ViewAccessLevel;
use entity_access::domain::ports::EntityAccessService;
@@ -139,6 +140,10 @@ pub struct GetEntityPropertiesResponse {
pub summary: String,
}
+impl ToolAnnotated for GetEntityProperties {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read entity properties");
+}
+
#[async_trait]
impl<T, A> AsyncTool<PropertiesToolContext<T, A>> for GetEntityProperties
where
diff --git a/crates/properties/src/inbound/toolset/list_tags.rs b/crates/properties/src/inbound/toolset/list_tags.rs
index 41b70fc696..ccd7020a3f 100644
--- a/crates/properties/src/inbound/toolset/list_tags.rs
+++ b/crates/properties/src/inbound/toolset/list_tags.rs
@@ -2,6 +2,7 @@
use crate::domain::service::PropertiesService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use models_properties::PropertyOwner;
@@ -59,6 +60,10 @@ pub struct ListTagsResponse {
// empty structs can't be deserialized;
pub struct ListTags {}
+impl ToolAnnotated for ListTags {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("List tags");
+}
+
#[async_trait]
impl<T, A> AsyncTool<PropertiesToolContext<T, A>> for ListTags
where
diff --git a/crates/properties/src/inbound/toolset/set_entity_property.rs b/crates/properties/src/inbound/toolset/set_entity_property.rs
index 16c1b3b711..6f16aad195 100644
--- a/crates/properties/src/inbound/toolset/set_entity_property.rs
+++ b/crates/properties/src/inbound/toolset/set_entity_property.rs
@@ -2,6 +2,7 @@
use crate::domain::service::PropertiesService;
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use entity_access::domain::models::EditAccessLevel;
@@ -190,6 +191,10 @@ pub struct SetEntityPropertyResponse {
pub message: String,
}
+impl ToolAnnotated for SetEntityProperty {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Set entity property");
+}
+
#[async_trait]
impl<T, A> AsyncTool<PropertiesToolContext<T, A>> for SetEntityProperty
where
diff --git a/crates/skills/src/inbound/toolset/list_skills.rs b/crates/skills/src/inbound/toolset/list_skills.rs
index 967d1f1262..79d5133d81 100644
--- a/crates/skills/src/inbound/toolset/list_skills.rs
+++ b/crates/skills/src/inbound/toolset/list_skills.rs
@@ -1,4 +1,5 @@
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
@@ -24,6 +25,10 @@ pub struct ListSkillsResponse {
pub results: Vec<SkillSearchResult>,
}
+impl ToolAnnotated for ListSkills {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("List skills");
+}
+
#[async_trait]
impl<Svc: SkillService> AsyncTool<SkillToolContext<Svc>> for ListSkills {
type Output = ListSkillsResponse;
diff --git a/crates/skills/src/inbound/toolset/search_skills.rs b/crates/skills/src/inbound/toolset/search_skills.rs
index fa331a5c96..0c609f2dab 100644
--- a/crates/skills/src/inbound/toolset/search_skills.rs
+++ b/crates/skills/src/inbound/toolset/search_skills.rs
@@ -1,4 +1,5 @@
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use schemars::JsonSchema;
@@ -73,6 +74,10 @@ pub struct SearchSkillsResponse {
pub results: Vec<SkillSearchResult>,
}
+impl ToolAnnotated for SearchSkills {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Search skills");
+}
+
#[async_trait]
impl<Svc: SkillService> AsyncTool<SkillToolContext<Svc>> for SearchSkills {
type Output = SearchSkillsResponse;
diff --git a/crates/soup/src/inbound/toolset/list_entities.rs b/crates/soup/src/inbound/toolset/list_entities.rs
index 0921d04344..1e59aa2603 100644
--- a/crates/soup/src/inbound/toolset/list_entities.rs
+++ b/crates/soup/src/inbound/toolset/list_entities.rs
@@ -7,6 +7,7 @@ use crate::domain::{
ports::SoupService,
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use email::domain::{models::PreviewView, ports::EmailService};
use filter_ast::Expr;
@@ -659,6 +660,10 @@ impl ListEntities {
}
}
+impl ToolAnnotated for ListEntities {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Browse workspace");
+}
+
#[async_trait]
impl<T, E> AsyncTool<SoupToolContext<T, E>> for ListEntities
where
diff --git a/crates/teams/src/inbound/toolset/list_team_members.rs b/crates/teams/src/inbound/toolset/list_team_members.rs
index 0bcc9ee0b4..3a1601f298 100644
--- a/crates/teams/src/inbound/toolset/list_team_members.rs
+++ b/crates/teams/src/inbound/toolset/list_team_members.rs
@@ -6,6 +6,7 @@ use crate::domain::{
team_repo::TeamMembersService,
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
+use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::{
models::{
@@ -76,6 +77,10 @@ pub struct ListTeamMembersResponse {
// empty structs can't be deserialized;
pub struct ListTeamMembers {}
+impl ToolAnnotated for ListTeamMembers {
+ const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("List team members");
+}
+
#[async_trait]
impl<TSvc, ESvc> AsyncTool<TeamToolContext<TSvc, ESvc>> for ListTeamMembers
where
diff --git a/services/mcp_service/src/tool_service.rs b/services/mcp_service/src/tool_service.rs
index 7ee25aa648..b63e18720d 100644
--- a/services/mcp_service/src/tool_service.rs
+++ b/services/mcp_service/src/tool_service.rs
@@ -4,10 +4,24 @@ use rmcp::{
handler::server::ServerHandler,
model::{
Content, ListToolsResult, PaginatedRequestParams, ServerCapabilities, ServerInfo, Tool,
+ ToolAnnotations,
},
};
use std::sync::Arc;
+/// Maps our protocol-agnostic annotations onto the MCP wire representation.
+///
+/// [`ToolKind`](ai_toolset::ToolKind) collapses `readOnlyHint`/`destructiveHint`
+/// into one choice, so this is the only place the two booleans are derived —
+/// they can never disagree.
+fn mcp_annotations(annotations: &ai_toolset::ToolAnnotations) -> ToolAnnotations {
+ ToolAnnotations::with_title(annotations.title)
+ .read_only(annotations.kind.read_only_hint())
+ .destructive(annotations.kind.destructive_hint())
+ .idempotent(annotations.idempotent)
+ .open_world(annotations.open_world)
+}
+
/// MCP server handler that extracts authenticated user identity from HTTP
/// request parts injected by rmcp's `StreamableHttpService`.
#[allow(
@@ -47,6 +61,8 @@ impl<Context> AuthenticatedToolService<Context> {
value.description.to_owned(),
Arc::new(value.input_schema.clone()),
)
+ .with_title(value.annotations.title)
+ .annotate(mcp_annotations(&value.annotations))
})
.collect()
}
diff --git a/services/mcp_service/src/tool_service/test.rs b/services/mcp_service/src/tool_service/test.rs
index 6158160f1a..ec6e871dcc 100644
--- a/services/mcp_service/src/tool_service/test.rs
+++ b/services/mcp_service/src/tool_service/test.rs
@@ -85,6 +85,78 @@ async fn empty_toolset_lists_no_tools() {
assert!(empty_service().tool_definitions().is_empty());
}
+/// Anthropic's connector directory rejects any tool missing a display title or
+/// the applicable `readOnlyHint`/`destructiveHint`, and any tool name over 64
+/// characters. Assert it against the toolset the server actually exposes, so a
+/// newly added tool can't quietly regress the submission.
+#[test]
+fn every_exposed_tool_meets_directory_requirements() {
+ let tools = ai_tools::mcp_tools();
+ assert!(
+ !tools.toolset.tools.is_empty(),
+ "the MCP toolset should not be empty"
+ );
+
+ for (name, tool) in tools.toolset.tools.iter() {
+ let annotations = mcp_annotations(&tool.annotations);
+
+ assert!(
+ name.len() <= 64,
+ "{name} exceeds the 64-character tool name limit"
+ );
+ assert!(
+ annotations
+ .title
+ .as_deref()
+ .is_some_and(|title| !title.trim().is_empty()),
+ "{name} has no display title"
+ );
+ assert!(
+ annotations.read_only_hint.is_some(),
+ "{name} has no readOnlyHint"
+ );
+ assert!(
+ annotations.destructive_hint.is_some(),
+ "{name} has no destructiveHint"
+ );
+ assert!(
+ !(annotations.read_only_hint == Some(true)
+ && annotations.destructive_hint == Some(true)),
+ "{name} claims to be both read-only and destructive"
+ );
+ }
+}
+
+#[test]
+fn read_only_tools_map_to_read_only_hint() {
+ let annotations = mcp_annotations(&ai_toolset::ToolAnnotations::read_only("Read document"));
+
+ assert_eq!(annotations.title.as_deref(), Some("Read document"));
+ assert_eq!(annotations.read_only_hint, Some(true));
+ assert_eq!(annotations.destructive_hint, Some(false));
+ assert_eq!(annotations.idempotent_hint, Some(true));
+ assert_eq!(annotations.open_world_hint, Some(false));
+}
+
+#[test]
+fn destructive_tools_map_to_destructive_hint() {
+ let annotations =
+ mcp_annotations(&ai_toolset::ToolAnnotations::destructive("Send email").with_open_world());
+
+ assert_eq!(annotations.title.as_deref(), Some("Send email"));
+ assert_eq!(annotations.read_only_hint, Some(false));
+ assert_eq!(annotations.destructive_hint, Some(true));
+ assert_eq!(annotations.open_world_hint, Some(true));
+}
+
+#[test]
+fn additive_tools_set_neither_hint() {
+ let annotations = mcp_annotations(&ai_toolset::ToolAnnotations::additive("Create document"));
+
+ assert_eq!(annotations.read_only_hint, Some(false));
+ assert_eq!(annotations.destructive_hint, Some(false));
+}
+
#[test]
fn authenticated_user_id_is_read_from_http_request_parts() {
let expected_user_id = MacroUserIdStr::try_from_email("[email protected]").unwrap();