Tools and Capabilities

Tools and Capabilities#

MassGen provides a comprehensive tools ecosystem that enables AI agents to perform complex tasks through three complementary systems. Tools extend agent capabilities beyond text generation to include code execution, file operations, web search, external API integration, and custom functionality.

Note

This is an overview of MassGen’s tools ecosystem. For detailed guides, see:

What Are Tools?#

Tools in MassGen are capabilities that agents can invoke during task execution. Unlike traditional function calls in your code, these tools are:

  • Discoverable: Agents automatically learn about available tools through JSON schemas

  • Backend-Agnostic: The same tool works across Claude, Gemini, OpenAI, and all other backends

  • Safely Isolated: Tools execute in controlled environments with timeouts and resource limits

  • Multimodal: Tools can return text, images, audio, or structured data

Tool Systems Overview#

MassGen provides four ways for agents to access tools:

  1. Backend Built-in Tools: Web search, code execution, file operations provided by model APIs

  2. MCP Integration: External tools through the Model Context Protocol

  3. Custom Tools: Your own Python functions registered via the Tool System

  4. AG2 Framework Tools: Tools from the AG2 framework (when using AG2 backend)

1. Backend Built-in Tools#

Different model providers offer built-in capabilities that agents can enable via YAML configuration.

Key Capabilities:

  • Web Search: Real-time information from the internet (Gemini, Grok, Claude, OpenAI)

  • Code Execution: Run Python code and scripts (OpenAI, Claude, Gemini, AG2)

  • File Operations: Read, write, and modify files (Claude Code natively, others via MCP)

Important

Code Execution: Two Different Options

MassGen supports two distinct code execution approaches:

  1. Backend Built-in (enable_code_execution/enable_code_interpreter): Runs in the provider’s sandbox (OpenAI, Claude, Gemini). Does NOT integrate with your local filesystem - code runs in an isolated cloud environment.

  2. MCP-based (enable_mcp_command_line): Runs on your local machine or Docker container. Full filesystem access - agents can read/write files in your project.

Use backend built-in for quick calculations and isolated code snippets. Use MCP-based for code that needs to interact with your project files.

See Code Execution for detailed comparison and configuration.

Quick Example:

agents:
  - id: "researcher"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"
      enable_web_search: true         # Built-in web search
      enable_code_execution: true     # Built-in code execution

Availability:

See Backend Configuration for the complete backend capabilities matrix showing which backends support which built-in tools.

2. MCP (Model Context Protocol) Integration#

The Model Context Protocol (MCP) is an open standard that connects AI agents to external tools and data sources. Think of it as USB-C for AI - a universal interface for tools.

What You Can Do:

  • Connect to external APIs (Weather, Discord, Twitter, Notion)

  • Access databases and file systems

  • Use browser automation (Playwright)

  • Search the web (Brave Search)

  • Integrate with custom services

Quick Example:

agents:
  - id: "agent_with_mcp"
    backend:
      type: "openai"
      model: "gpt-5-nano"
      mcp_servers:
        - name: "weather"
          type: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-weather"]

Key Features:

  • Standardized protocol for external tool integration

  • Works across all MassGen backends (except Azure OpenAI)

  • Support for multiple MCP servers per agent

  • Tool filtering and safety controls

  • Planning mode to prevent premature execution

See also

MCP Integration - Complete guide with MCP server configuration, common servers, tool filtering, planning mode, and security best practices

3. Custom Tools System#

MassGen’s Custom Tools System allows you to register your own Python functions as tools that agents can discover and use. This enables you to extend agent capabilities with domain-specific functionality.

What You Can Do:

  • Turn your Python functions into agent tools via YAML config

  • Automatic schema generation from function signatures and docstrings

  • Works across all MassGen backends (Claude, Gemini, OpenAI, etc.)

  • No need to modify MassGen internals

Your Tool File (my_tools/analyzer.py):

from massgen.tool import ExecutionResult, TextContent
import json

async def analyze_data(dataset: str, metrics: list) -> ExecutionResult:
    """Analyze dataset and compute metrics.

    Args:
        dataset: Path to dataset file
        metrics: List of metrics to compute (e.g., ["mean", "median", "count"])

    Returns:
        ExecutionResult with analysis results
    """
    # Load and analyze data
    with open(dataset, 'r') as f:
        data = json.load(f)

    results = {}
    if "count" in metrics:
        results["count"] = len(data)
    if "mean" in metrics and data:
        results["mean"] = sum(data) / len(data)
    if "median" in metrics and data:
        sorted_data = sorted(data)
        mid = len(sorted_data) // 2
        results["median"] = sorted_data[mid]

    output = f"Analysis Results:\n{json.dumps(results, indent=2)}"
    return ExecutionResult(
        output_blocks=[TextContent(data=output)]
    )

Your Config (config.yaml):

agents:
  - id: "analyst"
    backend:
      type: "claude"
      model: "claude-sonnet-4"
      custom_tools:
        - name: "analyze_data"
          path: "my_tools/analyzer.py"
          function: "analyze_data"
          category: "data_science"

Run:

massgen --config config.yaml "Analyze sales_data.csv"

See also

Custom Tools - Complete guide with working examples, built-in tools, configuration patterns, and troubleshooting

4. AG2 Framework Tools#

When using the AG2 backend, agents gain access to the AG2 framework’s execution environments and tools.

Supported Executors:

  • local - Execute code on local machine

  • docker - Execute in Docker container

  • jupyter - Execute in Jupyter kernel

  • yepcode - Execute in YepCode environment

Configuration:

agents:
  - id: "ag2_coder"
    backend:
      type: "ag2"
      agent_type: "ConversableAgent"
      llm_config:
        config_list:
          - model: "gpt-4"
            api_key: "${OPENAI_API_KEY}"
      code_execution_config:
        executor: "docker"
        work_dir: "coding"

See General Framework Interoperability for detailed AG2 tool configuration and usage.

Combining Tool Systems#

The real power comes from combining different tool systems to create agents with comprehensive capabilities.

All Three Systems Together#

agents:
  - id: "full_stack_agent"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"

      # 1. Built-in backend tools
      enable_web_search: true
      enable_code_execution: true

      # 2. External MCP tools
      mcp_servers:
        - name: "weather"
          type: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-weather"]

      # 3. Custom tools
      custom_tools:
        - path: "tools/analyzer.py"
          func: "analyze_data"
        - func: "run_python_script"

Result: Agent can search the web, execute code, check weather, and use your custom analysis functions.

Specialized Multi-Agent Configuration#

Different agents with different tool combinations:

agents:
  # Research agent: Web search + MCP
  - id: "researcher"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"
      enable_web_search: true
      mcp_servers:
        - name: "brave_search"
          type: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-brave-search"]

  # Development agent: File operations + Custom tools
  - id: "developer"
    backend:
      type: "claude_code"
      model: "claude-sonnet-4"
      cwd: "workspace"
      custom_tools:
        - func: "run_python_script"
        - func: "run_shell_script"

  # Data agent: Code execution + Custom analytics
  - id: "data_analyst"
    backend:
      type: "openai"
      model: "gpt-5-nano"
      enable_code_interpreter: true
      custom_tools:
        - path: "tools/stats.py"
          func: "calculate_statistics"
        - path: "tools/viz.py"
          func: "create_visualization"

Quick Start Examples#

Built-in Tools#

# Web search
massgen --model gemini-2.5-flash \
  "Research the latest AI developments and summarize key trends"

# Code execution
massgen --model gpt-5-nano \
  "Calculate the first 100 prime numbers and plot their distribution"

MCP Tools#

# Single MCP server (weather)
massgen \
  --config @examples/tools/mcp/gpt5_nano_mcp_example.yaml \
  "What's the weather forecast for New York this week?"

# Multiple MCP servers
massgen \
  --config @examples/tools/mcp/multimcp_gemini.yaml \
  "Find hotels in London and check the weather forecast"

Custom Tools#

# Custom Python tools
massgen \
  --config massgen/configs/tools/custom_tools/claude_code_custom_tool_example.yaml \
  "Calculate the sum of 15 and 27"

# Custom tools with MCP
massgen \
  --config massgen/configs/tools/custom_tools/gemini_custom_tool_with_mcp_example.yaml \
  "Test both custom and MCP tools together"

Choosing the Right Tool System#

Tool System

Best For

When to Use

Built-in Tools

Web search, basic code execution, file ops

Quick setup, standard capabilities

MCP Integration

External APIs, third-party services

Weather, databases, Discord, Twitter, browser automation

Custom Tools

Domain-specific functionality

Your own business logic, specialized algorithms, internal APIs

AG2 Framework

Complex multi-agent workflows

Research tasks, code generation with execution

Best Practices#

Tool Configuration#

  1. Enable only needed tools: Reduce API costs and improve agent focus

  2. Use MCP for external integrations: Standardized, reusable protocol

  3. Create custom tools for domain logic: Your unique functionality

  4. Test tools independently: Verify each tool works before multi-agent use

  5. Document tool requirements: Note required API keys, dependencies, and permissions

Security#

Warning

Tools can execute code, access files, and call external APIs. Always:

  • Review third-party MCP servers before use

  • Use tool filtering (allowed_tools/exclude_tools) to restrict capabilities

  • Enable planning mode for tools with side effects

  • Store API keys in .env files, never in configs

  • Test in isolated environments first

  • Set timeouts to prevent long-running operations

See Project Integration & Context Paths for secure file access configuration.

Performance#

  1. Lazy loading: Don’t register unnecessary tools

  2. Category management: Disable tool categories when not needed

  3. Tool filtering: Reduce available tools to improve agent decision-making

  4. Caching: MCP servers support caching for repeated requests

  5. Timeouts: Set reasonable timeouts for all tools

Common Issues#

Backend doesn’t support tool:

# ❌ Grok doesn't support code execution
backend:
  type: "grok"
  enable_code_interpreter: true

# ✅ Use OpenAI instead
backend:
  type: "openai"
  enable_code_interpreter: true

See Backend Configuration for complete backend capabilities matrix.

MCP server not found:

# Test MCP server
npx -y @modelcontextprotocol/server-weather

# Install globally for faster startup
npm install -g @modelcontextprotocol/server-weather

Custom tool not registered:

  • Verify the file path is correct relative to where you run massgen

  • Check the function name matches exactly

  • Ensure the function is defined in the file

  • See Custom Tools for detailed troubleshooting

Detailed Guides#

For in-depth information on each tool system:

🔌 MCP Integration

External tools via Model Context Protocol

  • MCP server configuration

  • Common servers (weather, search, Discord)

  • Tool filtering and safety

  • Planning mode

  • Multi-server setups

Read the MCP Integration guide →

🛠️ Custom Tools

Your own Python functions as tools

  • Write Python functions as tools

  • Register via YAML config

  • Built-in tools (code execution, file operations)

  • Works across all backends

  • 58 working examples

Read the Custom Tools guide →

🖥️ Computer Use

Browser and desktop automation tools

  • Gemini Computer Use (Google)

  • Claude Computer Use (Anthropic)

  • Simple browser automation (any model)

  • Visual feedback and screenshots

  • Multi-agent coordination

Read the Computer Use guide →

External Resources#