Tool System & MCP

Documentation Index

Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Core Responsibilities

1. Type Safety - Enforce action/observation schemas via Pydantic models
2. Schema Generation - Auto-generate LLM-compatible tool descriptions from Pydantic schemas
3. Execution Lifecycle - Validate inputs, execute logic, wrap outputs
4. Tool Registry - Discover and resolve tools by name or pattern

​

Tool System

​

Architecture Overview

​

Key Components

​

Action-Observation Pattern

• Input: dict[str, Any] (JSON arguments) → validated Action instance
• Output: Observation instance with structured result
• No knowledge of: Events, LLM messages, conversation state

​

Tool Definition

​

Pattern 1: Direct Instantiation (Simple Tools)

1. Action - Pydantic model with visualize property for display
2. Observation - Pydantic model with to_llm_content property for LLM
3. ToolExecutor - Stateless executor with __call__(action) → observation
4. ToolDefinition - Direct instantiation with executor instance

​

Pattern 2: Subclass with Factory (Stateful Tools)

1. Action/Observation - Same as Pattern 1
2. ToolExecutor - Stateful executor with __init__() for configuration and optional close() for cleanup
3. MyTool(ToolDefinition) - Subclass with @classmethod create(conv_state, ...) factory method
4. Factory Method - Returns sequence of configured tool instances

​

Tool Annotations

• LLM-based Security risk prediction automatically added for tools with readOnlyHint=False
• Annotations help LLMs reason about tool safety and side effects

​

Tool Registry

1. Tool (Spec) - Configuration object with name (e.g., “BashTool”) and params (e.g., {"working_dir": "/workspace"})
2. Resolver Lookup - Registry finds the registered resolver for the tool name
3. Factory Invocation - Resolver calls the tool’s .create() method with params and conversation state
4. Instance Creation - Tool instance(s) are created with configured executors
5. Agent Usage - Instances are added to the agent’s tools_map for execution

​

File Organization

openhands-tools/openhands/tools/my_tool/
├── __init__.py           # Export MyTool
├── definition.py         # Action, Observation, MyTool(ToolDefinition)
├── impl.py              # MyExecutor(ToolExecutor)
└── [other modules]      # Tool-specific utilities

• Separation of Concerns - Public API separate from implementation
• Avoid Circular Imports - Import impl only inside create() method
• Consistency - All tools follow same structure for discoverability

​

MCP Integration

​

Architecture Overview

​

Key Components

​

Sync/Async Bridge

• Background Event Loop - Executes async code from sync contexts
• Timeout Support - Configurable timeouts for MCP operations
• Error Handling - Wraps MCP errors in observations
• Connection Pooling - Reuses connections across tool calls

​

Tool Discovery Flow

1. Spawn Server - Launch MCP server via stdio protocol (using MCPClient)
2. List Tools - Call MCP tools/list endpoint to retrieve available tools
3. Parse Schemas - Extract tool names, descriptions, and inputSchema from MCP response
4. Create Definitions - For each tool, call MCPToolDefinition.create() which:
   • Creates an MCPToolExecutor instance bound to the tool name and client
   • Wraps the MCP tool metadata in MCPToolDefinition
   • Uses generic MCPToolAction as the action type (NOT dynamic models yet)
5. Add to Agent - All MCPToolDefinition instances are added to agent’s tools_map during initialize() (bypasses ToolRegistry)
6. Lazy Validation - Dynamic Pydantic models are generated lazily when:
   • action_from_arguments() is called (argument validation)
   • to_openai_tool() is called (schema export to LLM)

​

MCP Server Configuration

from openhands.sdk import Agent

agent = Agent(
    mcp_config={
        "mcpServers": {
            "fetch": {
                "command": "uvx",
                "args": ["mcp-server-fetch"]
            },
            "filesystem": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
            }
        }
    }
)

​

Component Relationships

• Native → Registry → tools_map: Native tools resolved via ToolRegistry
• MCP → tools_map: MCP tools bypass registry, added directly during initialize()
• tools_map → LLM: Generate schemas describing all available capabilities
• Agent → tools_map: Execute actions, receive observations
• tools_map → Conversation: Read state for context-aware execution
• tools_map → Security: Tool annotations inform risk assessment

​

See Also

• Agent Architecture - How agents select and execute tools
• Events - ActionEvent and ObservationEvent structures
• Security Analyzer - Action risk assessment
• Skill Architecture - Embedding MCP configs in repository skills
• Custom Tools Guide - Building your own tools
• FastMCP Documentation - Underlying MCP client library