Custom Tools & Toolkits

Hive leverages the Model Context Protocol (MCP) to provide a standardized, extensible way for agents to interact with external systems. Tools are the primary mechanism by which agents perform actions—such as reading files, querying databases, or calling external APIs.

Overview

In Hive, tools are organized into Toolkits. A Toolkit is a collection of related functions registered via an MCP server. The framework uses these tool definitions to provide the LLM with the necessary context (via docstrings and type hints) to invoke functionality during a run.

Creating Custom Tools

Custom tools are defined using the FastMCP class. Each tool is a decorated Python function that includes comprehensive docstrings. These docstrings are critical because they act as the "manual" for the AI agent.

Basic Tool Definition

To create a tool, define a function and use the @mcp.tool() decorator.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyToolkit")

@mcp.tool()
def calculate_metric(base_value: float, multiplier: float = 1.2) -> dict:
    """
    Purpose:
        Calculates a proprietary business metric based on input values.
    
    When to use:
        Use this tool when the user asks for advanced forecasting or 
        performance metrics.
    
    Args:
        base_value: The starting numeric value for calculation.
        multiplier: The coefficient to apply (default: 1.2).
    """
    result = base_value * multiplier
    return {"success": True, "result": result}

Context-Aware Tools

For production agents, tools often need to operate within a specific sandbox or session. Hive typically passes session metadata (workspace_id, agent_id, session_id) to tools to ensure security and isolation.

@mcp.tool()
def view_custom_log(
    log_name: str,
    workspace_id: str,
    session_id: str
) -> dict:
    """
    Reads a specific log file within the agent's session sandbox.
    """
    # Use internal security utilities to resolve paths safely
    # Example: secure_path = get_secure_path(log_name, workspace_id, session_id)
    return {"content": "...log data..."}

Toolkits and Registration

A Toolkit is a modular group of tools. You can register multiple tools to a single MCP instance and then load that instance into the Hive ToolRegistry.

Registering Tools Programmatically

If you are building a custom agent runner, you register tools via the ToolRegistry:

from framework.runner.tool_registry import ToolRegistry

registry = ToolRegistry()

# Tools can be loaded from a configuration file (MCP servers)
registry.load_mcp_config("path/to/mcp_servers.json")

# Or retrieved for the runtime
tools = list(registry.get_tools().values())
executor = registry.get_executor()

The Tool Registry Configuration (mcp_servers.json)

You can define external toolkits in a JSON configuration, allowing the agent to connect to remote MCP servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": ["-m", "aden_tools.tools.file_system_toolkits"],
      "env": {
        "BASE_WORKSPACE_PATH": "/tmp/hive-workspaces"
      }
    }
  }
}

Best Practices for Tool Development

To ensure high reliability and "self-improving" capabilities within the Hive framework, follow these guidelines:

1. Detailed Docstrings: The LLM relies entirely on the docstring to understand why and how to use a tool. Include a "Purpose" and "Rules & Constraints" section.
2. Type Hints: Always use Python type hints. Hive uses these to generate the JSON Schema for the tool call.
3. Structured Returns: Return dictionaries rather than raw strings. This allows the agent to parse specific fields (e.g., success, error, data) and enables better error handling in the EventLoopNode.
4. Error Handling: Wrap tool logic in try-except blocks. Return an informative error message in the dictionary instead of letting the tool crash. This allows the agent's "coding agent" to potentially fix the workflow.

Built-in Toolkits

Hive comes with several pre-configured toolkits located in tools/src/aden_tools/tools/:

| Toolkit | Description | Key Tools | | :--- | :--- | :--- | | File System | Secure file operations within a session sandbox. | view_file, write_file, patch_file | | Search | External web search capabilities (e.g., Brave Search). | web_search | | Credentials | Interfaces with Hive's internal Credential Store. | get_api_key, refresh_oauth_token |

Integrating with the Runtime

Once tools are registered, they are passed to the AgentRuntime. The runtime manages the ToolExecutor, which handles the actual invocation during graph execution.

runtime = create_agent_runtime(
    graph=my_graph,
    tools=tools,
    tool_executor=executor,
    # ... other config
)

During execution, any LLMNode or EventLoopNode in your graph that is configured to use tools will have access to the entire registered toolkit. All tool invocations, inputs, and results are automatically logged at Level 3 (TOOL LOGS) in the Hive runtime logging system.