Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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>whereC: 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsnew file mode 100644index 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.rsnew file mode 100644index 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.rsindex 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.rsindex 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 generatordiff --git a/crates/ai_toolset/src/toolset/tool_object/tool_async.rs b/crates/ai_toolset/src/toolset/tool_object/tool_async.rsindex 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 @@ whereToolContext: FromRef<ToolSetContext> + Send + Sync + 'static,T: JsonSchema+ AsyncTool<ToolContext, Output = O>+ + ToolAnnotated+ for<'de> Deserialize<'de>+ 'static+ Send@@ -183,6 +185,7 @@ wherename,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 @@ wherename: 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.rsindex 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.rsindex b93e48138c..cecddecb8c 100644--- a/crates/ai_toolset/src/toolset/types.rs+++ b/crates/ai_toolset/src/toolset/types.rs@@ -1,6 +1,7 @@//! typesuse 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 @@ wherepub fn add_tool<T, ToolContext>(mut self) -> SelfwhereToolContext: 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 @@ wherepub fn add_user_tool<T, ToolContext>(mut self) -> SelfwhereToolContext: 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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 ReadCallRecordwherediff --git a/crates/channels/src/inbound/toolset/read_channel_message_context.rs b/crates/channels/src/inbound/toolset/read_channel_message_context.rsindex 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 ReadChannelMessageContextwherediff --git a/crates/channels/src/inbound/toolset/read_channel_messages.rs b/crates/channels/src/inbound/toolset/read_channel_messages.rsindex 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 ReadChannelMessageswherediff --git a/crates/channels/src/inbound/toolset/read_channel_thread.rs b/crates/channels/src/inbound/toolset/read_channel_thread.rsindex 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 ReadChannelThreadwherediff --git a/crates/channels/src/inbound/toolset/send_channel_message.rs b/crates/channels/src/inbound/toolset/send_channel_message.rsindex 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 SendChannelMessagewherediff --git a/crates/chat/src/domain/service/chat/test.rs b/crates/chat/src/domain/service/chat/test.rsindex 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.rsindex 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 ReadChatwherediff --git a/crates/crm/src/inbound/toolset/get_company.rs b/crates/crm/src/inbound/toolset/get_company.rsindex 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 GetCompanywherediff --git a/crates/crm/src/inbound/toolset/list_companies.rs b/crates/crm/src/inbound/toolset/list_companies.rsindex 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 ListCompanieswherediff --git a/crates/documents/src/inbound/toolset/create_document.rs b/crates/documents/src/inbound/toolset/create_document.rsindex 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 CreateDocumentwherediff --git a/crates/documents/src/inbound/toolset/edit_document.rs b/crates/documents/src/inbound/toolset/edit_document.rsindex 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 EditDocumentwherediff --git a/crates/documents/src/inbound/toolset/read_content.rs b/crates/documents/src/inbound/toolset/read_content.rsindex 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 ReadContentwherediff --git a/crates/documents/src/inbound/toolset/read_metadata.rs b/crates/documents/src/inbound/toolset/read_metadata.rsindex 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 ReadMetadatawherediff --git a/crates/documents/src/inbound/toolset/rename_document.rs b/crates/documents/src/inbound/toolset/rename_document.rsindex 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 RenameDocumentwherediff --git a/crates/email/src/inbound/toolset/get_thread.rs b/crates/email/src/inbound/toolset/get_thread.rsindex 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 GetThreadwherediff --git a/crates/email/src/inbound/toolset/list_inboxes.rs b/crates/email/src/inbound/toolset/list_inboxes.rsindex 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 ListInboxeswherediff --git a/crates/email/src/inbound/toolset/list_labels.rs b/crates/email/src/inbound/toolset/list_labels.rsindex 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 ListLabelswherediff --git a/crates/email/src/inbound/toolset/send_email.rs b/crates/email/src/inbound/toolset/send_email.rsindex 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 SendEmailwherediff --git a/crates/email/src/inbound/toolset/update_thread_labels.rs b/crates/email/src/inbound/toolset/update_thread_labels.rsindex 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 UpdateThreadLabelswherediff --git a/crates/import/src/inbound/toolset.rs b/crates/import/src/inbound/toolset.rsindex 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.rsindex 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 ListNotificationswhere@@ -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 MarkNotificationsSeenwhere@@ -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 MarkNotificationsDonewherediff --git a/crates/projects/src/inbound/toolset/create_project.rs b/crates/projects/src/inbound/toolset/create_project.rsindex 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 CreateProjectdiff --git a/crates/projects/src/inbound/toolset/move_to_project.rs b/crates/projects/src/inbound/toolset/move_to_project.rsindex 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 MoveToProjectdiff --git a/crates/projects/src/inbound/toolset/read_project.rs b/crates/projects/src/inbound/toolset/read_project.rsindex 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 ReadProjectdiff --git a/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rs b/crates/properties/src/inbound/toolset/bulk_set_entity_property_options.rsindex 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 BulkSetEntityPropertyOptionswherediff --git a/crates/properties/src/inbound/toolset/create_tag.rs b/crates/properties/src/inbound/toolset/create_tag.rsindex 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 CreateTagwherediff --git a/crates/properties/src/inbound/toolset/delete_tag.rs b/crates/properties/src/inbound/toolset/delete_tag.rsindex 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 DeleteTagwherediff --git a/crates/properties/src/inbound/toolset/edit_tag.rs b/crates/properties/src/inbound/toolset/edit_tag.rsindex 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 EditTagwherediff --git a/crates/properties/src/inbound/toolset/get_entity_properties.rs b/crates/properties/src/inbound/toolset/get_entity_properties.rsindex 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 GetEntityPropertieswherediff --git a/crates/properties/src/inbound/toolset/list_tags.rs b/crates/properties/src/inbound/toolset/list_tags.rsindex 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 ListTagswherediff --git a/crates/properties/src/inbound/toolset/set_entity_property.rs b/crates/properties/src/inbound/toolset/set_entity_property.rsindex 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 SetEntityPropertywherediff --git a/crates/skills/src/inbound/toolset/list_skills.rs b/crates/skills/src/inbound/toolset/list_skills.rsindex 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.rsindex 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.rsindex 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 ListEntitieswherediff --git a/crates/teams/src/inbound/toolset/list_team_members.rs b/crates/teams/src/inbound/toolset/list_team_members.rsindex 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 ListTeamMemberswherediff --git a/services/mcp_service/src/tool_service.rs b/services/mcp_service/src/tool_service.rsindex 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.rsindex 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();