python-sdk/docs/tools/index.md

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

• Core Libraries - Supporting packages (async, consensus, network)
• MCP Reference - Server documentation
• Agent Framework - Multi-agent SDK