Struct ToolUsage 

pub struct ToolUsage {
    pub when_to_use: Option<String>,
    pub when_not_to: Option<String>,
    pub preconditions: Vec<String>,
    pub cost: Option<String>,
    pub example: Option<String>,
    pub tier: Option<String>,
}

Reasoner-facing usage guidance for a capability. This is what lets a planner or the chat reasoner choose the right tool instead of guessing from a one-line description: when it applies, when it does not, what must be true first, roughly what it costs, and the safety tier the action carries (awareness ≠ permission — execution is still gated by the consent/audit path; this string is purely descriptive).

Every field is optional so the struct is backward-compatible on the wire (#[serde(default)] on the ToolDescriptor::usage field) and cheap to fill incrementally — MCP-sourced tools may carry none of it, a hand-authored native backend descriptor may carry all of it.

Free-text fields sourced from an untrusted MCP server are subject to the same injection caveat as ToolDescriptor::description; render them through sanitization before they reach a system prompt.

Fields

when_to_use: Option<String>

when_not_to: Option<String>

preconditions: Vec<String>

cost: Option<String>

Coarse cost hint — e.g. “free / local”, “network call”, “LLM tokens”.

example: Option<String>

A short example invocation or phrasing that triggers this capability.

tier: Option<String>

Safety tier as a string ("read", "write", "execute", "external", "destructive"). Kept as a plain string so the schema crate stays free of an identity dependency; registration sites stamp it from the known Tier equivalent.

Implementations

impl ToolUsage

pub fn is_empty(&self) -> bool

True when no guidance has been supplied — lets producers skip the field on the wire so MCP-sourced tools that carry none stay tidy.

Trait Implementations

impl Clone for ToolUsage

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 ToolUsage

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

Formats the value using the given formatter.

impl Default for ToolUsage

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ToolUsage

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ToolUsage

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.