Trait Tool 

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, Error>> + Send;

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

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.

Required Associated Types

type Name: ToolName

The type of name for this tool.

Required Methods

fn name(&self) -> Self::Name

Returns the tool’s strongly-typed name.

fn display_name(&self) -> &'static str

Human-readable display name for UI (e.g., “Read File” vs “read”).

Defaults to empty string. Override for better UX.

fn description(&self) -> &'static str

Human-readable description of what the tool does.

fn input_schema(&self) -> Value

JSON schema for the tool’s input parameters.

fn execute( &self, ctx: &ToolContext<Ctx>, input: Value, ) -> impl Future<Output = Result<ToolResult, Error>> + Send

Execute the tool with the given input.

Errors

Returns an error if tool execution fails.

Provided Methods

fn tier(&self) -> ToolTier

Permission tier for this tool.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<Ctx, P> Tool<Ctx> for WebSearchTool<P>

where Ctx: Send + Sync + 'static, P: SearchProvider + 'static,

Available on crate feature web only.

type Name = PrimitiveToolName

impl<Ctx, T> Tool<Ctx> for SimpleToolAdapter<T>

where T: SimpleTool<Ctx>,

type Name = DynamicToolName

impl<Ctx, T> Tool<Ctx> for TypedToolAdapter<T>

where T: TypedTool<Ctx>, Ctx: Send + Sync,

type Name = DynamicToolName

impl<Ctx: Send + Sync + 'static> Tool<Ctx> for AskUserQuestionTool

type Name = PrimitiveToolName

impl<Ctx: Send + Sync + 'static> Tool<Ctx> for TodoReadTool

type Name = PrimitiveToolName

impl<Ctx: Send + Sync + 'static> Tool<Ctx> for TodoWriteTool

type Name = PrimitiveToolName

impl<Ctx> Tool<Ctx> for LinkFetchTool

where Ctx: Send + Sync + 'static,

Available on crate feature web only.

type Name = PrimitiveToolName

impl<E: Environment + 'static, Ctx: Send + Sync + 'static> Tool<Ctx> for BashTool<E>

type Name = PrimitiveToolName

impl<E: Environment + 'static, Ctx: Send + Sync + 'static> Tool<Ctx> for EditTool<E>

type Name = PrimitiveToolName

impl<E: Environment + 'static, Ctx: Send + Sync + 'static> Tool<Ctx> for GlobTool<E>

type Name = PrimitiveToolName

impl<E: Environment + 'static, Ctx: Send + Sync + 'static> Tool<Ctx> for GrepTool<E>

type Name = PrimitiveToolName

impl<E: Environment + 'static, Ctx: Send + Sync + 'static> Tool<Ctx> for ReadTool<E>

type Name = PrimitiveToolName

impl<E: Environment + 'static, Ctx: Send + Sync + 'static> Tool<Ctx> for WriteTool<E>

type Name = PrimitiveToolName

impl<P, H, M, S, Ctx> Tool<Ctx> for SubagentTool<P, H, M, S>

where P: LlmProvider + Clone + 'static, H: AgentHooks + Clone + 'static, M: MessageStore + 'static, S: StateStore + 'static, Ctx: Send + Sync + 'static,

type Name = DynamicToolName

impl<T: McpTransport + 'static, Ctx: Send + Sync + 'static> Tool<Ctx> for McpToolBridge<T>

Available on crate feature mcp only.

type Name = DynamicToolName