Trait Tool

Source

pub trait Tool: Send + Sync {
    // Required methods
    fn schema(&self) -> ToolSchema;
    fn call<'life0, 'life1, 'async_trait>(
        &'life0 self,
        arguments: Value,
        state: &'life1 SharedState,
    ) -> Pin<Box<dyn Future<Output = Result<String, ToolError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided method
    fn protected_output(&self) -> bool { ... }
}

Expand description

A tool an agent can invoke.

A tool has two perspectives:

Tool::schema — the model perspective — tells the model what the tool is and what its arguments look like;
Tool::call — the execution perspective — actually runs the model-provided arguments and returns a text result for the model.

Implementations must be Send + Sync: the agent loop may execute tools concurrently on any thread. Tools that need to flow / share custom content across tools read and write the state parameter in call; tools that do not can ignore it (_state).

§Example

use molo::tool::{SharedState, Tool, ToolError, ToolSchema};
use serde_json::json;

// A demo tool: returns a fixed time.
struct TimeTool;

#[molo::async_trait]
impl Tool for TimeTool {
    fn schema(&self) -> ToolSchema {
        ToolSchema {
            name: "time".into(),
            description: "Return the current time".into(),
            parameters: json!({ "type": "object", "properties": {} }),
        }
    }

    async fn call(
        &self,
        _arguments: serde_json::Value,
        _state: &SharedState,
    ) -> Result<String, ToolError> {
        Ok("12:00".into())
    }
}

let tool = TimeTool;
assert_eq!(tool.schema().name, "time");

Required Methods§

Source

fn schema(&self) -> ToolSchema

Model perspective: this tool’s definition.

Source

fn call<'life0, 'life1, 'async_trait>( &'life0 self, arguments: Value, state: &'life1 SharedState, ) -> Pin<Box<dyn Future<Output = Result<String, ToolError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Execution perspective: run this tool.

arguments is the model-generated arguments JSON (parsed uniformly by the agent loop); state is the current agent’s shared state (a type-safe heterogeneous container, see SharedState) — tools that need to flow / share custom content across tools read and write it; tools that do not can ignore the parameter (_state). Returns result text, which the agent passes back to the model as ToolResult.

Provided Methods§

Source

fn protected_output(&self) -> bool

Whether the tool result is protected: marked on record, exempt from window trimming.

Used for persistent behavioral guidance such as skill bodies — if a tool result is trimmed by the window, the model silently degrades (it keeps running but loses the specialized instructions, with no visible error). Tools returning true have their results recorded via Memory::record_protected and are never trimmed by window Memory; the default is no protection.