Trait Tool 

pub trait Tool: Send + Sync {
    // Required methods
    fn spec(&self) -> &ToolSpec;
    fn invoke<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        request: ToolRequest,
        ctx: &'life1 mut ToolContext<'life2>,
    ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;

    // Provided methods
    fn current_spec(&self) -> Option<ToolSpec> { ... }
    fn proposed_requests(
        &self,
        _request: &ToolRequest,
    ) -> Result<Vec<Box<dyn PermissionRequest>>, ToolError> { ... }
}

The central abstraction for an executable tool in an agentkit agent.

Implement this trait to define a tool that an LLM can call. Each tool provides a ToolSpec describing its name, schema, and hints, optional permission requests via proposed_requests, and the actual execution logic in invoke.

Example

use agentkit_core::{MetadataMap, ToolOutput, ToolResultPart};
use agentkit_tools_core::{
    Tool, ToolContext, ToolError, ToolName, ToolRequest, ToolResult, ToolSpec,
};
use async_trait::async_trait;
use serde_json::json;

struct TimeTool {
    spec: ToolSpec,
}

impl TimeTool {
    fn new() -> Self {
        Self {
            spec: ToolSpec::new(
                ToolName::new("current_time"),
                "Returns the current UTC time",
                json!({ "type": "object" }),
            ),
        }
    }
}

#[async_trait]
impl Tool for TimeTool {
    fn spec(&self) -> &ToolSpec {
        &self.spec
    }

    async fn invoke(
        &self,
        request: ToolRequest,
        _ctx: &mut ToolContext<'_>,
    ) -> Result<ToolResult, ToolError> {
        Ok(ToolResult::new(ToolResultPart::success(
            request.call_id,
            ToolOutput::text("2026-03-22T12:00:00Z"),
        )))
    }
}

Required Methods

fn spec(&self) -> &ToolSpec

Returns the static specification for this tool.

fn invoke<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, request: ToolRequest, ctx: &'life1 mut ToolContext<'life2>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

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

Executes the tool and returns a result or error.

Errors

Return an appropriate ToolError variant on failure. Returning ToolError::AuthRequired causes the executor to emit a ToolInterruption::AuthRequired instead of treating it as a hard failure.

Provided Methods

fn current_spec(&self) -> Option<ToolSpec>

Returns the current specification for this tool, if it should be advertised right now.

Most tools are static and can rely on the default implementation, which clones spec. Override this when the description or input schema should reflect runtime state, or when the tool should be temporarily hidden from the model.

fn proposed_requests( &self, _request: &ToolRequest, ) -> Result<Vec<Box<dyn PermissionRequest>>, ToolError>

Returns permission requests the executor should evaluate before calling invoke.

The default implementation returns an empty list (no permissions needed). Override this to declare filesystem, shell, or custom permission requirements based on the incoming request.

Errors

Return ToolError::InvalidInput if the request input is malformed and permission requests cannot be constructed.

Implementors