Skip to content

Tools Overview

Complete documentation for all hanzo-tools-* packages.

Architecture: Tools follow HIP-0300 - the Unified MCP Tools Architecture with orthogonal operators and effect tracking.

Installation

# All tools (recommended)
pip install hanzo-mcp[tools-all]

# Core development tools
pip install hanzo-mcp[tools-dev]

# Individual packages
pip install hanzo-tools-shell hanzo-tools-browser

Tool Categories

HIP-0300 Core Operators

Primary operators organized by orthogonal axes:

Tool Axis Actions Description
fs Bytes + Paths read, write, edit, search, patch, tree Filesystem operations
id Identity hash, uri, ref, verify Content-addressable identity
code Symbols + Structure parse, transform, summarize Code analysis and transformation
proc Execution run, bg, signal, wait Process execution
vcs History + Diffs status, diff, commit, log Version control
test Validation check, build, test Validation loops
net Network search, fetch, download, crawl Network operations
plan Orchestration intent, route, compose Intent routing

Control Surfaces

Tool Surface Description
browser Web DOM Playwright automation (70+ actions)
computer OS Desktop Mac automation via pyautogui

Extended Operators

Tool Domain Description
lsp Semantic Stream Language server protocol (diagnostics, code_actions)
memory Knowledge Persistent memory and knowledge bases
todo Task Tracking Task management
reasoning Cognition Structured thinking (think, critic)
agent Multi-Agent Agent orchestration (run, list, status)
llm LLM Interface Unified LLM interface (llm, consensus)

Infrastructure

Package Tools Description
Core Base classes BaseTool, IdTool, ToolRegistry
Config 2 Configuration and mode management
Database 8 SQL and graph database operations
Vector 3 Semantic search with embeddings
Refactor 1 Code refactoring (rename, extract, inline)
Jupyter 1 Notebook read/edit/execute
Editor 3 Neovim integration
MCP 4 MCP server management

Quick Reference

Most Used Tools

# File operations
read(file_path="/path/to/file")
write(file_path="/path/to/file", content="...")
edit(file_path="/path/to/file", old_string="old", new_string="new")

# Command execution
cmd("ls -la")
cmd(["npm install", "npm build"], parallel=True)

# Search
search(pattern="TODO", path=".")
ast(pattern="def test_", path="/tests")

# Reasoning
think(thought="Analyzing the problem...")
critic(analysis="Code review findings...")

# Browser
browser(action="navigate", url="https://example.com")
browser(action="click", selector="button")

Tool Discovery

from importlib.metadata import entry_points

# Discover all available tools
for ep in entry_points(group="hanzo.tools"):
    tools = ep.load()
    print(f"{ep.name}: {[t.name for t in tools]}")

Architecture

All tools follow a consistent pattern:

from hanzo_tools.core import BaseTool, ToolContext

class MyTool(BaseTool):
    name = "my_tool"

    @property
    def description(self) -> str:
        return "Tool description"

    async def call(self, ctx: ToolContext, **params) -> str:
        # Implementation
        return result

See Also