Struct ToolDeclaration 

pub struct ToolDeclaration {
    pub name: String,
    pub description: String,
    pub parameters: Value,
    pub cache: Option<CacheTtl>,
    pub tool: Option<ToolId>,
}

A tool the model may ask for, as the request declares it.

Provider-neutral, because the two shapes differ in ways that are easy to get subtly wrong: Anthropic takes {name, description, input_schema} at the top level, while OpenAI wraps it as {type: "function", function: {name, description, parameters}}. A driver renders this into whichever it speaks, so a caller writes the declaration once.

What a declaration is not

It is not a grant. Declaring a tool tells the model the tool exists; it does not authorize the call. The model’s choice of tool and its arguments come back untrusted, are matched against the operator’s grants exactly, and are dispatched through cx.sink where field provenance and the egress ceiling apply. A framework that executes what the model asked for has authorized the model; this one authorizes the operator’s declaration and treats the model’s request as a suggestion.

Fields

name: String

The name the model will use when it asks for this tool.

description: String

What it does, for the model’s benefit.

Model-steering text outside every label. The model reads it as it reads the instruction, and no sink gate judges it, so it must come from a reviewed declaration — a grant’s description, or a typed tool’s own doc — never straight from a far side. An MCP server’s description is drafted into a grant for review (ToolGrant::drafted_from), not copied here.

parameters: Value

JSON Schema for the arguments.

Sent with provider-side strict enforcement when the provider accepts the schema. OpenAI supports only a subset for strict tools, so a valid schema with optional fields is sent non-strict rather than rejected by the API; typed local tools still deserialize the result exactly. Either way this is not a security control: a well-formed argument is still an untrusted one, and the field-provenance check is what authorizes it.

cache: Option<CacheTtl>

Cache everything up to and including this declaration, for this long.

Tools come first in the cache order (tools, system, messages), so a breakpoint on the last declaration caches the whole tool prefix. Anthropic and Bedrock honour it; drivers whose provider caches without being asked ignore it, which lets one declaration serve every provider.

tool: Option<ToolId>

The catalogue tool this offer stands for, when it stands for one.

Not sent and not in the effect key — the provider never sees it. It is what lets a skill answer the model’s call from the offer the model answered (StepCtx::call_tool_for), so the name a model is shown and the tool that runs meet in one place rather than in a second table the skill keeps.

Implementations

impl ToolDeclaration

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

Declare a tool that stands for nothing in a catalogue — one the skill answers itself.

pub fn offering( tool: ToolId, description: impl Into<String>, parameters: Value, ) -> Self

Offer a catalogue tool, under its wire name.

The declaration remembers the tool, so a call to it is answered with StepCtx::call_tool_for. Offer it under another name with named.

pub fn named(self, name: impl Into<String>) -> Self

The name the model is shown and calls this offer by.

pub const fn cache_breakpoint(self, ttl: CacheTtl) -> Self

Mark the end of a cached prefix here. See cache.

Trait Implementations

impl Clone for ToolDeclaration

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolDeclaration

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

Formats the value using the given formatter.

impl Eq for ToolDeclaration

impl PartialEq for ToolDeclaration

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ToolDeclaration