Tools

Built-in tools, MCP integration, and community tools

Tools extend the agent’s capabilities, enabling it to interact with external systems, execute code, and perform specialized tasks.

Tool Architecture

DeerFlow’s tools come from multiple sources:

Tools
├── Sandbox Tools      (bash, ls, read_file, write_file, str_replace)
├── Built-in Tools     (present_files, ask_clarification, view_image)
├── Community Tools    (web_search, web_fetch, image_search)
├── MCP Tools          (External tools via Model Context Protocol)
├── Sub-agent Tool     (task - delegate to sub-agents)
└── Custom Tools       (User-defined via config.yaml)

Tool Loading

Tools are assembled via get_available_tools():

from src.tools import get_available_tools

tools = get_available_tools(
    groups=["sandbox", "research"],  # From config.yaml
    include_mcp=True,                # Include MCP tools
    model_name="gpt-4",             # Current model
    subagent_enabled=True           # Include task() tool
)

Tool Sources (in order):

1. Config-defined tools (via reflection)
2. MCP tools (from enabled servers)
3. Built-in tools
4. Sub-agent tool (if enabled)

Sandbox Tools

Core filesystem and command execution tools:

bash

Execute shell commands in the sandbox

ls

List directory contents in tree format

read_file

Read file contents with optional line range

write_file

Write or append to files

str_replace

Replace text in files

Sandbox Tools Reference

Complete tool documentation

Built-in Tools

Tools available to all agents:

present_files

Make output files visible to the user.

Usage:

present_files([
    "/mnt/user-data/outputs/report.html",
    "/mnt/user-data/outputs/chart.png"
])

Validation:

• Only files in /mnt/user-data/outputs can be presented
• Files must exist
• Returns artifact metadata for frontend display

ask_clarification

Request clarification from the user (interrupts execution).

Usage:

ask_clarification(
    question="Which data format would you like: CSV or JSON?"
)

Behavior:

• Interrupts agent execution
• Returns control to user
• User response appended to conversation

view_image

Load image as base64 for vision-enabled models.

Usage:

view_image(
    path="/mnt/user-data/uploads/screenshot.png",
    description="Screenshot of the error"
)

Requirements:

• Model must have supports_vision: true
• Image formats: PNG, JPEG, GIF, WebP

Built-in Tools Reference

Detailed tool documentation

Community Tools

Pre-integrated external service tools:

web_search (Tavily)

Search the web for current information.

Configuration:

tools:
  - use: src.community.tavily:web_search
    group: research

Usage:

results = web_search(
    query="Latest AI research papers 2026",
    max_results=5
)

Requires: TAVILY_API_KEY environment variable

web_fetch

Fetch and extract content from web pages.

Providers: Tavily, Jina AI, Firecrawl

Configuration:

tools:
  - use: src.community.tavily:web_fetch
    group: research
  # Or
  - use: src.community.jina_ai:web_fetch
    group: research
  # Or
  - use: src.community.firecrawl:web_fetch
    group: research

Usage:

content = web_fetch(
    url="https://example.com/article"
)

image_search (DuckDuckGo)

Search for images.

Configuration:

tools:
  - use: src.community.image_search:image_search
    group: media

Usage:

images = image_search(
    query="mountain landscape",
    max_results=10
)

Community Tools Reference

All community tools

MCP Tools

Model Context Protocol (MCP) enables integration with external tools and services.

Configuration (extensions_config.json):

{
  "mcpServers": {
    "filesystem": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    }
  }
}

Features:

• stdio transport: Command-based servers
• HTTP/SSE transport: Web-based servers
• OAuth support: Automatic token management
• Lazy loading: Tools loaded on first use
• Cache invalidation: Detects config changes

MCP Integration Guide

Set up MCP servers

Sub-agent Tool

Delegate complex tasks to sub-agents.

Configuration:

subagents:
  enabled: true

Usage:

task(
    description="Research AI frameworks",
    prompt="Research TensorFlow, PyTorch, and JAX",
    subagent_type="general-purpose",
    max_turns=20
)

Features:

• Up to 3 concurrent sub-agents
• Isolated contexts
• Shared filesystem
• 15-minute timeout

Sub-agents

Learn about task delegation

Custom Tools

Add your own tools via config.yaml:

tools:
  - use: my_tools.custom:my_tool
    group: custom

Tool Function:

my_tools/custom.py

from langchain_core.tools import tool

@tool
def my_tool(param: str) -> str:
    """Tool description for the agent.
    
    Args:
        param: Parameter description
    
    Returns:
        Result description
    """
    # Tool implementation
    return f"Result: {param}"

Reflection System:

• use: module.path:variable_name resolved via resolve_variable()
• Validates against LangChain tool interface
• Supports any callable that returns a LangChain tool

Creating Custom Tools

Build your own tools

Tool Groups

Organize tools into logical groups:

tool_groups:
  - name: sandbox
    description: Filesystem and command execution
  
  - name: research
    description: Web search and content fetching
  
  - name: media
    description: Image search and generation
  
  - name: custom
    description: User-defined tools

tools:
  - use: src.community.tavily:web_search
    group: research
  
  - use: src.community.image_search:image_search
    group: media

Usage:

# Load specific groups
tools = get_available_tools(groups=["sandbox", "research"])

# Load all groups
tools = get_available_tools(groups=["*"])

Tool Calling Flow

1. Agent Decision: Agent decides to use a tool
2. Tool Call Message: AIMessage with tool_calls
3. Tool Execution: Tool function invoked
4. Tool Message: ToolMessage with result
5. Agent Processing: Agent processes result

Example:

Agent: "I need to read the data file"
  → AIMessage(tool_calls=[{"name": "read_file", "args": {"path": "data.csv"}}])

System: Execute read_file("/mnt/user-data/uploads/data.csv")
  → ToolMessage(content="col1,col2\n1,2\n3,4")

Agent: "The data has 2 rows and 2 columns..."

Error Handling

Tools should handle errors gracefully:

@tool
def my_tool(param: str) -> str:
    """My tool description."""
    try:
        result = do_something(param)
        return result
    except FileNotFoundError:
        return f"Error: File '{param}' not found"
    except Exception as e:
        return f"Error: {str(e)}"

Best Practices:

• Return error messages as strings (not raise exceptions)
• Include context in error messages
• Suggest fixes when possible

Tool Permissions

Skills can restrict tool usage:

SKILL.md frontmatter

---
name: my-skill
allowed-tools:
  - bash
  - read_file
  - write_file
---

When this skill is loaded, only the specified tools are available.

Next Steps

Sandbox Tools

Filesystem and command tools

Built-in Tools

Core agent tools

MCP Integration

Connect external tools

Custom Tools

Create your own tools