Trait Tool

Source

pub trait Tool: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn input_schema(&self) -> Value;
    fn call<'life0, 'life1, 'async_trait>(
        &'life0 self,
        input: Value,
        ctx: &'life1 ToolCtx,
    ) -> Pin<Box<dyn Future<Output = Result<ToolOutput>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn read_only(&self) -> bool { ... }
    fn capabilities(&self) -> Capabilities { ... }
    fn carried_state(&self) -> Option<CarriedState> { ... }
    fn spec(&self) -> ToolSpec { ... }
}

Required Methods§

Source

fn call<'life0, 'life1, 'async_trait>( &'life0 self, input: Value, ctx: &'life1 ToolCtx, ) -> Pin<Box<dyn Future<Output = Result<ToolOutput>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Provided Methods§

Source

fn read_only(&self) -> bool

Read-only tools skip the approval gate and are safe to run in parallel.

Source

fn capabilities(&self) -> Capabilities

Declared risk surface. The default is the conservative one for a tool nobody has classified: assume it does nothing special.

Source

fn carried_state(&self) -> Option<CarriedState>

State this tool holds that a compaction must not lose.

Compaction replaces the middle of a transcript with prose, and the measured failure mode is that a summariser preserves what is true and drops how far you got. Some of “how far you got” does not live in the messages at all — it lives in a tool — and for that state a summary is the wrong mechanism twice over: it is lossy, and the tool already has the exact current answer.

So a tool may hand its state to the compaction to be carried across verbatim. Three rules make this safe rather than a second source of truth:

It is read at compaction time, so it is current by construction. A stale copy is impossible because nothing stores one.
Exactly one copy survives: the carried block replaces the previous one rather than accumulating beside it, or an old list would sit in the prompt contradicting the new one.
It is for state the tool owns, not a summary of what happened. A tool that returned prose here would be smuggling a second summariser into the loop, unvalidated.

None — the default — means “nothing worth carrying”, which is the honest answer for every stateless tool.

Source