Trait Tool 

pub trait Tool: Send + Sync {
    // 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, ToolError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;

    // Provided methods
    fn mutability(&self) -> ToolMutability { ... }
    fn call_mutability(&self, _args: &Value) -> ToolMutability { ... }
    fn concurrency_safe(&self) -> bool { ... }
    fn call_concurrency_safe(&self, _args: &Value) -> bool { ... }
    fn execute_with_context<'life0, 'life1, 'async_trait>(
        &'life0 self,
        args: Value,
        _ctx: ToolExecutionContext<'life1>,
    ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait { ... }
    fn to_schema(&self) -> ToolSchema { ... }
}

Trait for implementing executable tools.

All tools must implement this trait to be registered with the tool registry.

Required Methods

• name() - Unique tool identifier
• description() - Human-readable tool description
• parameters_schema() - JSON Schema for tool parameters
• execute() - Async tool execution logic

Provided Methods

• to_schema() - Convert tool to LLM-compatible schema

Example

struct ReadFileTool;

#[async_trait]
impl Tool for ReadFileTool {
    fn name(&self) -> &str {
        "read_file"
    }

    fn description(&self) -> &str {
        "Read file contents from disk"
    }

    fn parameters_schema(&self) -> serde_json::Value {
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string"}
            },
            "required": ["path"]
        })
    }

    async fn execute(&self, args: Value) -> Result<ToolResult, ToolError> {
        let path = args["path"].as_str().unwrap();
        let content = tokio::fs::read_to_string(path).await?;
        Ok(ToolResult {
            success: true,
            result: content,
            display_preference: None,
        })
    }
}

Required Methods

fn name(&self) -> &str

fn description(&self) -> &str

Human-readable tool description for LLM.

fn parameters_schema(&self) -> Value

JSON Schema for tool parameters.

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Execute the tool with given arguments.

Provided Methods

fn mutability(&self) -> ToolMutability

Declares whether this tool is read-only or mutating for orchestration and parallel scheduling decisions. Defaults to mutating to stay conservative.

fn call_mutability(&self, _args: &Value) -> ToolMutability

Args-aware mutability hook. Defaults to the static mutability declaration.

fn concurrency_safe(&self) -> bool

Declares whether this tool can safely run in parallel with other read-only tools. Defaults to false so tools remain serialized unless they opt in explicitly.

fn call_concurrency_safe(&self, _args: &Value) -> bool

Args-aware parallel-safety hook. Defaults to the static declaration.

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, _ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Execute the tool with a streaming-capable context.

Default implementation falls back to execute() for tools that don’t need streaming.

fn to_schema(&self) -> ToolSchema

Convert tool to LLM-compatible schema.

Creates a ToolSchema suitable for LLM function calling.

Dyn Compatibility

This trait is dyn compatible.

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

Implementations on Foreign Types

impl Tool for BashInputTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, BashInputTool: 'async_trait,

impl Tool for BashOutputTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn concurrency_safe(&self) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, BashOutputTool: 'async_trait,

impl Tool for BashTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, BashTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, BashTool: 'async_trait,

impl Tool for ConclusionWithOptionsTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, ConclusionWithOptionsTool: 'async_trait,

impl Tool for EditTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EditTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, EditTool: 'async_trait,

impl Tool for EnterPlanModeTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, EnterPlanModeTool: 'async_trait,

impl Tool for ExitPlanModeTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, ExitPlanModeTool: 'async_trait,

impl Tool for GetFileInfoTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn concurrency_safe(&self) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, GetFileInfoTool: 'async_trait,

impl Tool for GlobTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn concurrency_safe(&self) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, GlobTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, GlobTool: 'async_trait,

impl Tool for GrepTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn concurrency_safe(&self) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, GrepTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, GrepTool: 'async_trait,

impl Tool for JsReplTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, JsReplTool: 'async_trait,

impl Tool for KillShellTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, KillShellTool: 'async_trait,

impl Tool for NotebookEditTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, NotebookEditTool: 'async_trait,

impl Tool for ReadTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn concurrency_safe(&self) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, ReadTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, ReadTool: 'async_trait,

impl Tool for RequestPermissionsTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, RequestPermissionsTool: 'async_trait,

impl Tool for SessionNoteTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn call_mutability(&self, args: &Value) -> ToolMutability

fn call_concurrency_safe(&self, args: &Value) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, _args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionNoteTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, SessionNoteTool: 'async_trait,

impl Tool for SlashCommandTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SlashCommandTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, SlashCommandTool: 'async_trait,

impl Tool for SleepTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn concurrency_safe(&self) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SleepTool: 'async_trait,

impl Tool for TaskTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, TaskTool: 'async_trait,

impl Tool for UpdateGoalTool

fn mutability(&self) -> ToolMutability

Treated as read-only for approval/scheduling purposes: it touches no filesystem or external state. The durable goal-state mutation happens in the engine post-execution handler (same pattern as session_note).

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, UpdateGoalTool: 'async_trait,

impl Tool for WebFetchTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn concurrency_safe(&self) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, WebFetchTool: 'async_trait,

impl Tool for WebSearchTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn concurrency_safe(&self) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, WebSearchTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, WebSearchTool: 'async_trait,

impl Tool for WorkspaceTool

fn name(&self) -> &str

fn description(&self) -> &str

fn mutability(&self) -> ToolMutability

fn call_mutability(&self, args: &Value) -> ToolMutability

fn call_concurrency_safe(&self, args: &Value) -> bool

fn parameters_schema(&self) -> Value

fn execute<'life0, 'async_trait>( &'life0 self, args: Value, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, WorkspaceTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, WorkspaceTool: 'async_trait,

impl Tool for WriteTool

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, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, WriteTool: 'async_trait,

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, args: Value, ctx: ToolExecutionContext<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, WriteTool: 'async_trait,

Implementors