Crate neuromance_tools 

neuromance-tools

Tool execution framework for Neuromance LLM library.

This crate provides a flexible system for defining, registering, and executing tools that can be called by Large Language Models (LLMs). It includes built-in tools, support for custom tool implementations, and integration with the Model Context Protocol (MCP).

Core Components

• ToolImplementation: Trait for defining custom tools with execution logic
• ToolRegistry: Thread-safe registry for managing tool definitions
• ToolExecutor: High-level interface for tool execution with argument parsing
• mcp: Model Context Protocol client and server integration

Built-in Tools

• BooleanTool: Returns boolean values based on conditions
• ThinkTool: Enables chain-of-thought reasoning for LLMs
• TodoWriteTool / TodoReadTool: Task management tools for agents

Example: Creating and Executing a Custom Tool

use neuromance_tools::{ToolImplementation, ToolExecutor};
use neuromance_common::tools::{Tool, Function};
use serde_json::{json, Value};
use async_trait::async_trait;
use anyhow::Result;

// Define a custom tool
struct GreetingTool;

#[async_trait]
impl ToolImplementation for GreetingTool {
    fn get_definition(&self) -> Tool {
        Tool {
            r#type: "function".to_string(),
            function: Function {
                name: "greet".to_string(),
                description: "Greet a person by name".to_string(),
                parameters: json!({
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "The person's name"
                        }
                    },
                    "required": ["name"]
                }),
            },
        }
    }

    async fn execute(&self, args: &Value) -> Result<String> {
        let name = args["name"].as_str().unwrap_or("stranger");
        Ok(format!("Hello, {}!", name))
    }

    fn is_auto_approved(&self) -> bool {
        true // This tool can execute without user approval
    }
}

// Register and use the tool
let mut executor = ToolExecutor::new();
executor.add_tool(GreetingTool);

// Get all tool definitions to send to the LLM
let tools = executor.get_all_tools();

MCP Integration

The mcp module provides Model Context Protocol support for connecting to external tool servers and exposing tools via MCP:

use neuromance_tools::mcp::{McpManager, McpClientConfig};

let mut manager = McpManager::new();

// Connect to an MCP server
let config = McpClientConfig {
    name: "filesystem".to_string(),
    command: "npx".to_string(),
    args: vec!["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        .into_iter()
        .map(String::from)
        .collect(),
    env: None,
};

manager.add_server(config).await?;
let tools = manager.get_all_tools().await?;

Tool Auto-Approval

Tools can be marked as “auto-approved” via the ToolImplementation::is_auto_approved method. Auto-approved tools execute without requiring user confirmation, which is useful for safe, read-only operations.

Thread Safety

The ToolRegistry uses DashMap for concurrent access, making it safe to use from multiple async tasks without additional synchronization.

Modules

generic

mcp

Structs

BooleanTool

A tool that returns a boolean result based on the agent’s analysis Used for binary decisions like goal verification

ThinkTool

A tool that allows the agent to record thoughts and reasoning Used for making the agent’s thinking process visible in the context

TodoReadTool

Tool for reading the current todo list

TodoWriteTool

Tool for writing/updating the todo list

ToolExecutor

ToolRegistry

Traits

ToolImplementation

Functions

create_todo_tools

Create a pair of TodoRead and TodoWrite tools that share the same storage