Crate tools_kit 

Executable Local and MCP tools.

The public hierarchy is Toolset → ToolHandler. Toolset is cloneable and owns shared source lifecycle; each ToolHandler is a unique resumable invocation state machine. Callers implement ToolsetBackend directly and retain its exact associated handler. Toolset::from_backend optionally normalizes that hierarchy into supplied handles at the sole public root seam.

Supporting API is grouped under declaration, execution, interaction, local, mcp, and schema.

use tools_kit::{
    ToolHandlerBackend, Toolset, ToolsetBackend,
    declaration::{ToolInfo, ToolName},
    execution::{ToolHandlerInput, ToolHandlerOutput, ToolInvocation, ToolResult},
    local::ToolRegistration,
    schema::JsonSchema,
};

let name = ToolName::new("ping")?;
let info = ToolInfo::new(
    name.clone(),
    JsonSchema::strict(serde_json::json!({"type": "object"})),
);
let toolset = Toolset::local(vec![ToolRegistration::function(
    info,
    |_invocation| async { Ok(ToolResult::text("pong")) },
)])?;
let mut handler = toolset.tool_handler(name).await?;
let output = handler
    .step(ToolHandlerInput::Invoke(ToolInvocation {
        call_id: Some("call-1".to_owned()),
        arguments: serde_json::json!({}),
    }))
    .await;
let cleanup = toolset.shutdown().await;
let ToolHandlerOutput::Completed(result) = output? else { panic!("completion expected") };
assert!(!result.is_error);
assert!(matches!(result.content.as_slice(), [tools_kit::execution::ToolContent::Text { text, .. }] if text == "pong"));
cleanup?;

Choose a workflow

Audience	Start here
Application builders	Local registration and caller interactions, terminal results and failures, configured MCP clients and servers
Custom-backend implementers	Complete executable ToolsetBackend example, then the optional Toolset::from_backend normalization seam

Local construction performs no network request. Configuring an MCP connection is passive, but connecting or serving requires its external transport. The optional mcp-server feature adds a separately owned server; stopping it never shuts down the shared executable Toolset. No Handler normalization constructor exists.

Modules

declaration

Tool names and source-neutral executable declarations. Tool identities and complete executable declarations.

execution

Invocation, continuation, and completed-result values. Invocation inputs, resumable transitions, and completed tool outcomes.

interaction

Portable caller interactions requested during execution. Caller input requested by a suspended tool invocation.

local

In-process tool registration and interaction context. Local executable registrations and declared caller interactions.

mcp

MCP client configuration and optional independent server support. MCP client construction and independently owned server lifecycle.

schema

JSON Schema values and validation diagnostics. JSON Schema declarations, rendering preferences, and validation diagnostics.

Macros

tool

Builds a typed local registration.

Structs

ToolHandler

Opaque resumable handler for one selected executable tool. One handler owns one invocation. Start with Invoke, resume only the current interaction with its exact id, and use Cancel for cancellation. A completed result is terminal; a model-visible failure is a completed result with is_error. Import ToolHandlerBackend to call behavior on the supplied handle.

Toolset

Opaque cloneable Toolset over Local, MCP, or downstream behavior. Clones share admission and cleanup. Dropping a clone alone does not initiate asynchronous cleanup; explicitly await ToolsetBackend::shutdown.

Enums

ToolError

Portable executable-tool errors.

Traits

ToolHandlerBackend

Public implementation contract for one unique resumable tool handler. One handler owns one invocation. Start with Invoke, resume only the current interaction with its exact id, and use Cancel for cancellation. A completed result is terminal; a model-visible failure is a completed result with is_error. Import ToolHandlerBackend to call behavior on the supplied handle.

ToolsetBackend

Public implementation contract for one shared executable tool source. Use this trait directly with concrete caller implementations and their exact associated handlers. Toolset::from_backend is optional normalization when a supplied Toolset is needed. Shared shutdown obligations apply to both forms.