Trait Tool

Source

pub trait Tool: Send + Sync {
    type Input: DeserializeOwned + JsonSchema;

    // Required methods
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn execute(
        &self,
        input: Self::Input,
    ) -> impl Future<Output = Result<ToolResult, ToolError>> + Send;

    // Provided methods
    fn input_schema(&self) -> Value { ... }
    fn format_input_plain(&self, params: &Value) -> String { ... }
    fn format_input_ansi(&self, params: &Value) -> String { ... }
    fn format_input_markdown(&self, params: &Value) -> String { ... }
    fn format_output_plain(&self, result: &ToolResult) -> String { ... }
    fn format_output_ansi(&self, result: &ToolResult) -> String { ... }
    fn format_output_markdown(&self, result: &ToolResult) -> String { ... }
}

Expand description

Trait for implementing tools that can be used by AI agents.

Tools define an input type with #[derive(Deserialize, JsonSchema)] to automatically generate JSON schemas from Rust types, providing excellent developer experience.

§Async Tools Example

use mixtape_core::{Tool, ToolResult, ToolError};
use schemars::JsonSchema;
use serde::Deserialize;
use std::time::Duration;

#[derive(Deserialize, JsonSchema)]
struct DelayInput {
    /// Duration in milliseconds
    ms: u64,
}

struct DelayTool;

impl Tool for DelayTool {
    type Input = DelayInput;

    fn name(&self) -> &str { "delay" }
    fn description(&self) -> &str { "Wait for a duration" }

    fn execute(&self, input: Self::Input) -> impl std::future::Future<Output = Result<ToolResult, ToolError>> + Send {
        async move {
            // Async operations work naturally
            tokio::time::sleep(Duration::from_millis(input.ms)).await;
            Ok(format!("Waited {}ms", input.ms).into())  // Converts to ToolResult::Text
        }
    }
}

§Returning JSON Data

Tools can return structured JSON data:

use mixtape_core::{Tool, ToolResult, ToolError};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Deserialize, JsonSchema)]
struct CalculateInput {
    a: i32,
    b: i32,
}

#[derive(Serialize)]
struct CalculateOutput {
    sum: i32,
    product: i32,
}

struct CalculateTool;

impl Tool for CalculateTool {
    type Input = CalculateInput;

    fn name(&self) -> &str { "calculate" }
    fn description(&self) -> &str { "Perform calculations" }

    fn execute(&self, input: Self::Input) -> impl std::future::Future<Output = Result<ToolResult, ToolError>> + Send {
        async move {
            let output = CalculateOutput {
                sum: input.a + input.b,
                product: input.a * input.b,
            };
            ToolResult::json(output).map_err(Into::into)
        }
    }
}