Trait ToolMeta

Source

pub trait ToolMeta {
    const NAME: &'static str;
    const DESCRIPTION: &'static str;
    const EFFECT: Effect;
}

Expand description

A tool’s static identity: the name a model calls it by, a human description, and its side-effect Effect class.

This is the metadata half of the tool contract, split out from ToolHandler on purpose (see the derive seam). It carries no behavior and no associated types, so a proc-macro can generate it from struct-level attributes with nothing to infer.

The three members are associated constants because a native Rust tool knows all three at compile time. (Tools whose identity is known only at runtime, such as MCP-backed tools, do not implement this trait at all; they implement the type-erased DynTool directly, whose name/description/effect are methods.)

§The derive seam

Tool definition is a derive plus a hand-written impl:

#[derive(Tool)]
#[tool(effect = "write", description = "Create a Jira ticket")]
struct CreateTicket;

impl ToolHandler for CreateTicket {
    type Input = TicketRequest;
    type Output = TicketRef;
    async fn call(&self, ctx: &ToolCtx, input: TicketRequest) -> Result<...> { ... }
}

The split between these two traits is exactly the split between what the macro writes and what the user writes:

#[derive(Tool)] generates the ToolMeta impl. It reads the struct name for NAME (overridable by a name = "..." attribute), the description = "..." attribute for DESCRIPTION, and the effect = "read" | "idempotent" | "write" attribute for EFFECT. It generates no call body and touches none of the typed input or output.
The user writes the ToolHandler impl. They choose the Input and Output types and write the async call. The input JSON Schema is not hand-written: it is derived from Input by schemars, surfaced by the provided ToolHandler::input_schema method.

Because the metadata lives in its own trait with no reference to Input, Output, or call, the macro never has to parse or reason about the handler body. That is the whole reason for the split, and it is why this trait must stay behavior-free.