Struct Tool 

pub struct Tool { /* private fields */ }

A tool definition. Built with Tool::function, Tool::dynamic, Tool::provider_defined or Tool::provider_executed.

Implementations

impl Tool

pub fn into_builder(self) -> ToolBuilder<JsonValue>

Reopens this tool for configuration, preserving its definition and callbacks.

The builder’s execute closure receives JSON input; the existing input schema and executor are retained until explicitly replaced.

Examples

use ferrin_tool::{Tool, ToolError};
use ferrin_spec::JsonObject;
let tool = Tool::provider_defined("provider.search", JsonObject::new()).build();
let executable = tool.into_builder()
    .execute(|input: serde_json::Value, _| async move {
        Ok::<_, ToolError>(input)
    })
    .build();
assert!(executable.is_executable());

pub fn function<I: DeserializeOwned + JsonSchema + 'static>() -> ToolBuilder<I>

A function tool whose input schema is derived from I (draft-07, additionalProperties: false on objects).

pub fn function_with_schema( input_schema: Schema<JsonValue>, ) -> ToolBuilder<JsonValue>

A function tool with an explicit JSON schema; the execute closure receives the raw JSON input.

pub fn dynamic(input_schema: Schema<JsonValue>) -> ToolBuilder<JsonValue>

A dynamic tool (runtime-defined schema, untyped input and output).

pub fn provider_defined( id: impl Into<String>, args: JsonObject, ) -> ToolBuilder<JsonValue>

A provider-defined tool executed by the application. The input schema defaults to “any”; provider crates set the real one.

pub fn provider_executed( id: impl Into<String>, args: JsonObject, ) -> ToolBuilder<JsonValue>

A provider-executed tool.

impl Tool

pub fn kind(&self) -> &ToolKind

The kind.

pub fn description(&self) -> Option<&Description>

The description declaration.

pub fn title(&self) -> Option<&str>

The title.

pub fn input_schema(&self) -> &Schema<JsonValue>

The input schema (erased to JSON).

pub fn output_schema(&self) -> Option<&Schema<JsonValue>>

The output schema, if declared.

pub fn context_schema(&self) -> Option<&Schema<JsonValue>>

The context schema, if declared.

pub fn executor(&self) -> Option<&Arc<dyn ToolExecute>>

The executor, if the tool is executed by the application.

pub fn is_executable(&self) -> bool

Returns true when the tool has an executor.

pub fn needs_approval(&self) -> &NeedsApproval

The approval declaration.

pub fn strict(&self) -> Option<bool>

Strict-mode request.

pub fn input_examples(&self) -> &[JsonObject]

Example inputs.

pub fn metadata(&self) -> Option<&JsonObject>

Metadata propagated to tool calls (not sent to the model).

pub fn provider_options(&self) -> Option<&ProviderOptions>

Provider options sent with the tool definition.

pub fn hooks(&self) -> &ToolHooks

Input lifecycle hooks.

pub fn to_model_output(&self) -> Option<&ToModelOutputFn>

Custom model-output conversion.

pub fn caller_definition(&self) -> Option<&ToolCallerDefinition>

Caller definition, when this tool can call other tools.

pub fn with_provider_options( self, provider_options: Option<ProviderOptions>, ) -> Self

Returns a copy with different provider options.

pub async fn resolve_description( &self, ctx: DescriptionContext, ) -> Option<String>

Resolves the description for a call (None when the tool has none).

pub fn definition( &self, name: ToolName, description: Option<String>, ) -> ToolDefinition

Builds the provider-facing definition under name.

pub fn validate_input( &self, name: &ToolName, input: JsonValue, ) -> Result<JsonValue, TypeValidationError>

Validates an input against the input schema.

Errors

Returns the validation error with field: "tool input" and the tool name as entity.

pub fn validate_context( &self, name: &ToolName, context: Option<JsonValue>, ) -> Result<Option<JsonValue>, TypeValidationError>

Validates the selected tool context, preserving it when no schema is set.

Errors

Returns the validation error with field: "tool context".

pub fn validate_named_context( &self, name: &ToolName, contexts: Option<&JsonValue>, ) -> Result<Option<JsonValue>, TypeValidationError>

Selects this tool’s entry from a named context map and validates it.

The map is keyed by the registered tool name. Missing entries remain absent without a schema and are validated as JSON null with a schema.

Errors

Returns a validation error for a non-object context map or when the selected entry does not satisfy this tool’s context schema.

pub fn execute( &self, input: JsonValue, ctx: ToolContext, ) -> Option<ToolOutputStream>

Starts an execution; None when the tool has no executor.

Trait Implementations

impl Clone for Tool

fn clone(&self) -> Tool

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Tool

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

Formats the value using the given formatter.