Struct ToolMetadata 

#[non_exhaustive]
pub struct ToolMetadata {
    pub name: String,
    pub description: String,
    pub input_schema: Value,
    pub output_schema: Option<Value>,
    pub version: Option<String>,
    pub effect: ToolEffect,
    pub idempotent: bool,
    pub retry_hint: Option<RetryHint>,
    pub typical_duration: Option<Duration>,
}

Declarative description of a tool.

Every field is plain-data; constructed once (typically in the tool’s own new()) and returned by reference from Tool::metadata. The runtime treats this as authoritative — codecs render it into the on-the-wire ToolSpec, OTel layers stamp gen_ai.tool.* attributes from it, Approver defaults route off effect, and retry middleware honours retry_hint.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

name: String

Stable identifier the model uses to call this tool. Must be unique within a ToolRegistry. Conventionally snake_case.

description: String

Human-readable description shown to the model. Used to help the model decide when to call this tool — write it like a function docstring.

input_schema: Value

JSON Schema for the input payload that Tool::execute accepts. Codecs translate this into the vendor’s tool schema format.

output_schema: Option<Value>

Optional JSON Schema describing the output shape. Vendors that support strict tool-output schemas (OpenAI’s strict: true, Anthropic’s response format hints) read this. None = untyped JSON.

version: Option<String>

Optional version string. Surfaces in OTel (gen_ai.tool.version) and in audit events so operators can distinguish between tool revisions when behaviour changes.

effect: ToolEffect

Side-effect classification. Drives default Approver behaviour (Destructive → require approval) and is rendered to the LLM so the model can reason about safety on its own.

idempotent: bool

true when calling the tool repeatedly with the same input produces the same effect (no incremental change). Retry middleware uses this as the cheap binary version of retry_hint.is_some().

retry_hint: Option<RetryHint>

Per-tool retry policy hint. None (the default) means the tool is not retried by middleware.

typical_duration: Option<Duration>

Best-guess execution time for dashboards / scheduling. Used only as a hint — the runtime never enforces it as a deadline (use ExecutionContext::deadline for that).

Implementations

impl ToolMetadata

pub fn function( name: impl Into<String>, description: impl Into<String>, input_schema: Value, ) -> Self

Construct a function-tool descriptor with conservative defaults (effect = ReadOnly, no retry, no version). Customise via the with_* chain.

pub fn with_output_schema(self, schema: Value) -> Self

Attach an output schema.

pub fn with_version(self, version: impl Into<String>) -> Self

Attach a version string.

pub const fn with_effect(self, effect: ToolEffect) -> Self

Override the side-effect classification.

pub fn to_tool_spec(&self) -> ToolSpec

Project this metadata into the wire-shaped ToolSpec codecs encode for the model. Inspection helper used by crate::tools::Toolset::tool_specs and capability manifests. cache_control defaults to None — operators that need a per-tool cache directive set it on the ToolSpec itself.

pub const fn with_idempotent(self, idempotent: bool) -> Self

Mark the tool idempotent — repeat calls with the same input produce the same effect.

pub const fn with_retry_hint(self, hint: RetryHint) -> Self

Attach a retry hint. Implies idempotent = true because a non-idempotent tool that opts into retries is a bug.

pub const fn with_typical_duration(self, duration: Duration) -> Self

Attach a typical-duration hint.

Trait Implementations

impl Clone for ToolMetadata

fn clone(&self) -> ToolMetadata

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ToolMetadata

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.