Trait Tool
pub trait Tool:
Send
+ Sync
+ Attributable {
// Required methods
fn name(&self) -> &str;
fn description(&self) -> &str;
fn parameters_schema(&self) -> Value;
fn execute<'life0, 'async_trait>(
&'life0 self,
args: Value,
) -> Pin<Box<dyn Future<Output = Result<ToolResult, Error>> + Send + 'async_trait>>
where 'life0: 'async_trait,
Self: 'async_trait;
// Provided methods
fn requires_unrestricted_principal(&self) -> bool { ... }
fn output_schema(&self) -> Option<Value> { ... }
fn param_domains(&self) -> Vec<(&'static str, OptionDomain)> { ... }
fn invocation_triggers(&self) -> Vec<String> { ... }
fn execute_with_context<'life0, 'life1, 'async_trait>(
&'life0 self,
args: Value,
context: &'life1 ToolExecutionContext,
) -> Pin<Box<dyn Future<Output = Result<ToolResult, Error>> + Send + 'async_trait>>
where 'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait { ... }
fn spec(&self) -> ToolSpec { ... }
}Required Methods§
Sourcefn description(&self) -> &str
fn description(&self) -> &str
Human-readable description
Sourcefn parameters_schema(&self) -> Value
fn parameters_schema(&self) -> Value
JSON schema for parameters
Provided Methods§
Sourcefn requires_unrestricted_principal(&self) -> bool
fn requires_unrestricted_principal(&self) -> bool
True when this tool starts nested execution without carrying the RPC principal’s current tool and agent ceilings. Constrained RPC sessions must omit it. Wrappers forward the target’s value so a renamed skill cannot bypass that restriction. This describes implementation support, not a stored authorization decision.
Sourcefn output_schema(&self) -> Option<Value>
fn output_schema(&self) -> Option<Value>
JSON schema describing the structured output this tool attaches to
ToolOutput::data, when it declares one. None means the tool
emits display text only; authoring surfaces fall back to
sample-derived shapes from captured runs.
Sourcefn param_domains(&self) -> Vec<(&'static str, OptionDomain)>
fn param_domains(&self) -> Vec<(&'static str, OptionDomain)>
Option domains for parameters whose value sets live in runtime config rather than the static schema (channel refs, peer targets, …). Surfaces resolve these through the runtime to render real selectable choices. Default: no domain-typed parameters.
Sourcefn invocation_triggers(&self) -> Vec<String>
fn invocation_triggers(&self) -> Vec<String>
Lowercase phrases that suggest an inbound message wants this tool — e.g. routing wording or configured destination names for a delivery tool. A pre-turn prefilter may scan the message against these and nudge the model to consider the tool; the tool itself is never called by the prefilter.
Matching contract: case-insensitive, word-boundary — a trigger
matches only where it is bounded by non-alphanumeric characters or the
message ends (see invocation_trigger_matches). So dev does not
fire inside device and ops does not fire inside stops; a trigger
only hits as a whole word or phrase. Entries should still be wording
that, taken whole, indicates this tool — avoid single common words.
A config-derived name that happens to equal a common word can still
over-fire; the hint is advisory (the model, not the prefilter, decides
to call), so the cost of a false positive is a wasted nudge, never an
action. Entries derived from runtime config (aliases, group names)
must be computed live per call, never cached across reloads. Default:
no triggers; the tool does not participate in prefilter hints.
Sourcefn execute_with_context<'life0, 'life1, 'async_trait>(
&'life0 self,
args: Value,
context: &'life1 ToolExecutionContext,
) -> Pin<Box<dyn Future<Output = Result<ToolResult, Error>> + Send + 'async_trait>>where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
fn execute_with_context<'life0, 'life1, 'async_trait>(
&'life0 self,
args: Value,
context: &'life1 ToolExecutionContext,
) -> Pin<Box<dyn Future<Output = Result<ToolResult, Error>> + Send + 'async_trait>>where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
Execute with turn-scoped cancellation while preserving legacy tools.
Tools that start child work can override this method to pass the
context or a child token explicitly, and use ToolExecutionContext::run
to scope and cancel their execution future.
Sourcefn spec(&self) -> ToolSpec
fn spec(&self) -> ToolSpec
Assemble this tool’s spec. The default recomposes it from
parameters_schema() and allocates a fresh Arc per call, so tools
with large stored schemas override it to hand out Arc::clone
instead (see McpToolWrapper). Delegating wrappers around a
dyn Tool MUST forward spec() to the inner tool — relying on this
default silently reintroduces a per-iteration deep clone of the
inner schema and breaks Arc identity for downstream sharing.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".