Trait Tool 

pub trait Tool: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> Value;
    fn invoke<'life0, 'async_trait>(
        &'life0 self,
        args: Value,
        ctx: ToolCtx,
    ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;

    // Provided methods
    fn classify(&self, _args: &Value) -> ToolClass { ... }
    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 invoke<'life0, 'async_trait>( &'life0 self, args: Value, ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

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

The sole execution entry: returns the call’s per-call ToolOutcome (Completed / Running / NeedsHuman), or a ToolError for infrastructure / argument failures (preserved from the former execute).

Every tool is context-aware now — the former execute / execute_with_context split is gone, and ctx is owned so an invoke future can be moved into a detached drive task for latency-adaptive promotion.

Provided Methods

fn classify(&self, _args: &Value) -> ToolClass

Per-call scheduling + permission-gating class (args-aware). Folds the former mutability/call_mutability/concurrency_safe/ call_concurrency_safe hooks into one value. Defaults to the conservative ToolClass::MUTATING_SERIAL (mutating, serial, not promotable).

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 invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

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

impl Tool for BashOutputTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, _args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

fn invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, 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 invoke<'life0, 'async_trait>( &'life0 self, args: Value, ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

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

impl Tool for ConclusionWithOptionsTool

fn name(&self) -> &str

fn description(&self) -> &str

fn parameters_schema(&self) -> Value

fn invoke<'life0, 'async_trait>( &'life0 self, args: Value, ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, 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 invoke<'life0, 'async_trait>( &'life0 self, args: Value, ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

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

impl Tool for EnterPlanModeTool

fn name(&self) -> &str

fn description(&self) -> &str

fn parameters_schema(&self) -> Value

fn invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, 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 invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

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

impl Tool for GetFileInfoTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, _args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

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

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

impl Tool for GlobTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, _args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

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

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

impl Tool for GrepTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, _args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

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

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

impl Tool for JsReplTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, _args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

fn invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, 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 invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, 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 invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

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

impl Tool for ReadTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, _args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

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

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

impl Tool for RequestPermissionsTool

fn name(&self) -> &str

fn description(&self) -> &str

fn parameters_schema(&self) -> Value

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

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

impl Tool for SessionNoteTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

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

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

impl Tool for SlashCommandTool

fn name(&self) -> &str

fn description(&self) -> &str

fn parameters_schema(&self) -> Value

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

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

impl Tool for SleepTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, _args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

fn invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, 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 invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

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

impl Tool for UpdateGoalTool

fn classify(&self, _args: &Value) -> ToolClass

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 invoke<'life0, 'async_trait>( &'life0 self, args: Value, _ctx: ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

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

impl Tool for WebFetchTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, _args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

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

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

impl Tool for WebSearchTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, _args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

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

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

impl Tool for WorkspaceTool

fn name(&self) -> &str

fn description(&self) -> &str

fn classify(&self, args: &Value) -> ToolClass

fn parameters_schema(&self) -> Value

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

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

impl Tool for WriteTool

fn name(&self) -> &str

fn description(&self) -> &str

fn parameters_schema(&self) -> Value

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

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

Implementors