Trait Tool

Source

pub trait Tool<Ctx>: Send + Sync {
    type Name: ToolName;

    // Required methods
    fn name(&self) -> Self::Name;
    fn display_name(&self) -> &'static str;
    fn description(&self) -> &'static str;
    fn input_schema(&self) -> Value;
    fn execute(
        &self,
        ctx: &ToolContext<Ctx>,
        input: Value,
    ) -> impl Future<Output = Result<ToolResult>> + Send;

    // Provided method
    fn tier(&self) -> ToolTier { ... }
}

Expand description

Definition of a tool that can be called by the agent.

Tools have a strongly-typed Name associated type that determines how the tool name is serialized for LLM communication.

§Native Async Support

This trait uses Rust’s native async functions in traits (stabilized in Rust 1.75). You do NOT need the async_trait crate to implement this trait.

§Cooperative cancellation

The agent loop races every tool’s execute() future against the run’s ToolContext::cancel_token and, when configured, against ToolContext::tool_timeout. If either fires the SDK drops the in-flight execute() future and synthesises a balanced tool_result ("Cancelled by user" or a timeout message). Dropping a future runs its destructors but cannot, on its own, reclaim OS resources a tool has handed to the kernel.

Subprocess contract: a tool that spawns a child process MUST make the process die when its execute() future is dropped. The two supported ways to satisfy this are:

Build the command with tokio::process::Command::kill_on_drop(true), so the child is killed when the Child handle is dropped together with the cancelled future (this is what the SDK’s MCP stdio transport does), or
Observe ToolContext::cancel_token directly and kill() the child when it fires.

A tool that holds a subprocess open without either of these will leak the process when cancelled or timed out — the synthesised tool_result keeps the conversation balanced, but the orphaned OS process is the tool author’s bug, not the SDK’s.