Trait Tool

Source

pub trait Tool:
    Sized
    + WasmCompatSend
    + WasmCompatSync {
    type Args: for<'de> Deserialize<'de> + WasmCompatSend + WasmCompatSync;
    type Output: IntoToolOutput;
    type Error: Error + WasmCompatSend + WasmCompatSync + 'static;

    const NAME: &'static str;

    // Required methods
    fn description(&self) -> String;
    fn parameters(&self) -> Value;
    fn call(
        &self,
        context: &mut ToolContext,
        args: Self::Args,
    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + WasmCompatSend;

    // Provided methods
    fn annotations(&self) -> ToolAnnotations { ... }
    fn footprint(&self, args: &Self::Args) -> Touches { ... }
    fn map_error(&self, error: Self::Error) -> ToolExecutionError { ... }
}

Expand description

A typed LLM tool.

Tool authors provide metadata and exactly one execution method. Runtime context and host-only result metadata share the ToolContext path. Rig’s object-safe dispatch boundary is private; use DynamicTool when the tool name or callback is only known at runtime.

Required Associated Constants§

Source

const NAME: &'static str

Unique registration and provider-facing name.

Required Associated Types§

Source

type Args: for<'de> Deserialize<'de> + WasmCompatSend + WasmCompatSync

Typed JSON arguments.

Source

type Output: IntoToolOutput

Output convertible into Rig’s canonical model presentation.

Every owned serializable value implements IntoToolOutput automatically. ToolResultContent and Vec<ToolResultContent> preserve rich content when returned directly; use ToolOutput when constructing the presentation explicitly.

Source

type Error: Error + WasmCompatSend + WasmCompatSync + 'static

Typed error returned by direct calls to this tool.

Rig normalizes this error into ToolExecutionError only at the erased dispatch boundary. This keeps ordinary ? propagation and typed unit tests available to tool authors without creating a second runtime error representation.

Required Methods§

Source

fn description(&self) -> String

Model-facing description.

Source

fn parameters(&self) -> Value

JSON Schema for arguments.

Source

fn call( &self, context: &mut ToolContext, args: Self::Args, ) -> impl Future<Output = Result<Self::Output, Self::Error>> + WasmCompatSend

Execute the tool.

Provided Methods§

Source

fn annotations(&self) -> ToolAnnotations

What calling the tool does to the world, for the host’s policies (approval, plan mode, which calls run side by side). Nothing is stated by default, which reads as the protocol’s defaults (ToolAnnotations).

Source

fn footprint(&self, args: &Self::Args) -> Touches

What a call with args may read and change, so a host runs the calls of one reply that touch different things side by side. The default reads it from the annotations: a read-only tool reads anything, any other writes anything.

Source

fn map_error(&self, error: Self::Error) -> ToolExecutionError

Normalize a typed author-facing error for runtime policy and telemetry.

The default preserves concrete sources for operators and exposes safe kind-level model feedback. An existing ToolExecutionError retains its classification and model output. Override to supply deliberate domain feedback.