Struct ToolRegistry 

pub struct ToolRegistry<Ctx = ()>
where
    Ctx: Send + Sync + 'static,
{ /* private fields */ }

A registry of tool handlers, indexed by name.

Generic over context type Ctx which is passed to tool handlers on execution. Default is () for backwards compatibility.

Provides validation of tool call arguments against their schemas and parallel execution of multiple tool calls.

Interceptors

Tool execution can be wrapped with interceptors for cross-cutting concerns like logging, approval gates, or rate limiting:

use llm_stack::{ToolRegistry, tool_fn};
use llm_stack::intercept::{InterceptorStack, ToolExec, Approval, ApprovalDecision};

let mut registry: ToolRegistry<()> = ToolRegistry::new()
    .with_interceptors(
        InterceptorStack::<ToolExec<()>>::new()
            .with(Approval::new(|req| {
                if req.name.starts_with("dangerous_") {
                    ApprovalDecision::Deny("Not allowed".into())
                } else {
                    ApprovalDecision::Allow
                }
            }))
    );

Implementations

impl<Ctx: Send + Sync + 'static> ToolRegistry<Ctx>

pub fn new() -> Self

Creates an empty registry.

pub fn register( &mut self, handler: impl ToolHandler<Ctx> + 'static, ) -> &mut Self

Registers a tool handler.

If a handler with the same name already exists, it is replaced.

pub fn register_shared( &mut self, handler: Arc<dyn ToolHandler<Ctx>>, ) -> &mut Self

Registers a shared tool handler.

pub fn get(&self, name: &str) -> Option<&Arc<dyn ToolHandler<Ctx>>>

Returns the handler for the given tool name.

pub fn contains(&self, name: &str) -> bool

Returns whether a tool with the given name is registered.

pub fn definitions(&self) -> Vec<ToolDefinition>

Returns the definitions of all registered tools.

Pass this to ChatParams::tools to tell the model which tools are available.

pub fn len(&self) -> usize

Returns the number of registered tools.

pub fn is_empty(&self) -> bool

Returns true if no tools are registered.

pub fn without<'a>(&self, names: impl IntoIterator<Item = &'a str>) -> Self

Returns a new registry excluding the named tools.

Useful for creating scoped registries in Master/Worker patterns where workers should not have access to certain tools (e.g., spawn_task).

Example

use llm_stack::ToolRegistry;

let master_registry: ToolRegistry<()> = ToolRegistry::new();
// ... register tools ...

// Workers can't spawn or use admin tools
let worker_registry = master_registry.without(["spawn_task", "admin_tool"]);

pub fn only<'a>(&self, names: impl IntoIterator<Item = &'a str>) -> Self

Returns a new registry with only the named tools.

Useful for creating minimal registries with specific capabilities.

Example

use llm_stack::ToolRegistry;

let full_registry: ToolRegistry<()> = ToolRegistry::new();
// ... register tools ...

// Read-only registry with just search tools
let search_registry = full_registry.only(["search_docs", "search_web"]);

pub fn with_interceptors( self, interceptors: InterceptorStack<ToolExec<Ctx>>, ) -> Self

Sets the interceptor stack for all tool executions.

Interceptors run in the order added (first = outermost). They can inspect, modify, or block tool calls before they reach the handler.

Example

use llm_stack::{ToolRegistry, tool_fn};
use llm_stack::intercept::{InterceptorStack, ToolExec, Approval, ApprovalDecision, Retry};

let registry: ToolRegistry<()> = ToolRegistry::new()
    .with_interceptors(
        InterceptorStack::<ToolExec<()>>::new()
            .with(Approval::new(|req| {
                if req.name == "dangerous" {
                    ApprovalDecision::Deny("Not allowed".into())
                } else {
                    ApprovalDecision::Allow
                }
            }))
            .with(Retry::default())
    );

pub async fn execute(&self, call: &ToolCall, ctx: &Ctx) -> ToolResult

Executes a single tool call with schema validation and optional retry.

1. Looks up the handler by ToolCall::name
2. Validates arguments against the tool’s parameter schema
3. Runs the call through interceptors (if any)
4. Invokes the handler with the provided context
5. If the tool has retry configuration and execution fails, retries with exponential backoff

Returns a ToolResult (always succeeds at the outer level). Execution errors are captured in ToolResult::is_error.

pub async fn execute_all( &self, calls: &[ToolCall], ctx: &Ctx, parallel: bool, ) -> Vec<ToolResult>

Executes multiple tool calls, preserving order.

When parallel is true, all calls run concurrently via futures::future::join_all. When false, they run sequentially.

Trait Implementations

impl<Ctx> Clone for ToolRegistry<Ctx>

where Ctx: Send + Sync + 'static,

fn clone(&self) -> Self

Clone the registry.

This is cheap — it clones Arc pointers to handlers, not the handlers themselves.

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

Performs copy-assignment from source.

impl<Ctx> Debug for ToolRegistry<Ctx>

where Ctx: Send + Sync + 'static,

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

Formats the value using the given formatter.

impl<Ctx> Default for ToolRegistry<Ctx>

where Ctx: Send + Sync + 'static,

fn default() -> Self

Returns the “default value” for a type.

impl McpRegistryExt for ToolRegistry<()>

async fn register_mcp_service<S: McpService + 'static>( &mut self, service: &Arc<S>, ) -> Result<usize, McpError>

Registers all tools from an MCP service.

async fn register_mcp_tools_by_name<S: McpService + 'static>( &mut self, service: &Arc<S>, tool_names: &[&str], ) -> Result<usize, McpError>

Registers specific tools from an MCP service by name.