Tool Loading Tutorial¶

Complete Tutorial to loading and managing tools in ToolUniverse

This Tutorial covers two main approaches to load and access ToolUniverse tools: Python API using load_tools() method and MCP (Model Context Protocol) server using terminal commands.

Python API: Using load_tools()¶

The load_tools() method is the primary way to load tools when using ToolUniverse programmatically in Python.

Note

For complete Python API documentation, see API Reference for the full API reference.

tooluniverse.execute_function.ToolUniverse.load_tools(self, categories=None, tool_type=None, exclude_tools=None, exclude_categories=None, include_tools=None, tool_config_files=None, tools_file=None, include_tool_types=None, exclude_tool_types=None, python_files=None, quiet=True)

Load tools into the instance, with optional filtering.

Parameters:

categories (list, optional) – Tool category names to load. If None, all categories are loaded. Use list_categories() to see available names.
tool_type (list, optional) – Deprecated alias for categories.
exclude_tools (list, optional) – Tool names to exclude. Supports glob patterns (e.g. ["EuropePMC_*"]).
exclude_categories (list, optional) – Category names to skip entirely.
include_tools (list or str, optional) – Only load these tools. Supports glob patterns (e.g. ["EuropePMC_*", "ChEMBL_*"]). Pass a file path string to read names from a text file (one per line).
tool_config_files (dict, optional) – Extra JSON config files to load. Format: {"category_name": "/path/to/config.json"}.
tools_file (str, optional) – Deprecated. Pass a file path to include_tools instead.
python_files (list, optional) – List of Python file paths (str or Path) to import as user tools. Each file should contain @register_tool-decorated classes. Example: python_files=["/path/to/my_tool.py"].
include_tool_types (list, optional) – Only load tools whose type field is in this list (e.g. ["RESTTool", "GraphQLTool"]).
exclude_tool_types (list, optional) – Skip tools whose type field is in this list.
quiet (bool, optional) – Suppress missing-API-key warnings and .env.template generation. Default True. Pass False to see which keys are missing.

Examples

# Load everything (default) tu.load_tools()

# Load only two categories tu.load_tools(categories=[“ChEMBL”, “EuropePMC”])

# Load tools by name with glob wildcards tu.load_tools(include_tools=[“EuropePMC_*”, “ChEMBL_get_molecule_*”])

# Combine: exclude one category, exclude specific tools tu.load_tools(

exclude_categories=[“tool_finder”], exclude_tools=[“EuropePMC_slow_tool”],

)

Basic Usage¶

Load all available tools:

from tooluniverse import ToolUniverse

# Initialize ToolUniverse
tu = ToolUniverse()

# Load all tools from all categories
tu.load_tools()

# Check how many tools were loaded
print(f"Loaded {len(tu.all_tools)} tools")

# List first 5 tools
tool_names = tu.list_built_in_tools(mode='list_name')
for tool in tool_names[:5]:
    print(f"  • {tool}")

Selective Tool Loading¶

Load specific tool categories:

# Load only specific categories
tu.load_tools(tool_type=["uniprot", "ChEMBL", "opentarget"])

# Load tools but exclude certain categories
tu.load_tools(exclude_categories=["mcp_auto_loader", "special_tools"])

Load specific tools by name:

# Load only specific tools
tu.load_tools(include_tools=[
    "UniProt_get_entry_by_accession",
    "ChEMBL_get_molecule_by_chembl_id",
    "OpenTargets_get_associated_targets_by_disease_efoId"
])

# Load tools from a file
tu.load_tools(tools_file="/path/to/tool_names.txt")

Advanced Filtering¶

Filter by tool types:

# Include only specific tool types
tu.load_tools(include_tool_types=["OpenTarget", "ChEMBLTool"])

# Exclude specific tool types
tu.load_tools(exclude_tool_types=["ToolFinderEmbedding", "Unknown"])

Exclude specific tools:

# Load all tools except specific ones
tu.load_tools(exclude_tools=["problematic_tool", "slow_tool"])

Load Additional Configurations¶

Add custom tool configuration files:

# Load additional config files
tu.load_tools(tool_config_files={
    "custom_tools": "/path/to/custom_tools.json",
    "local_analysis": "/path/to/local_tools.json"
})

Note: tool_config_files is a dictionary of tool category names and the path to the tool configuration file, but it does not mean that the tool is loaded. You need to load the tool with tool_type or include_tools or include_tool_types.

Combined Parameters¶

Combine multiple loading options:

tu.load_tools(
    tool_type=["uniprot", "ChEMBL", "custom"],              # Load specific categories
    exclude_tools=["problematic_tool"],            # Exclude specific tools
    exclude_tool_types=["Unknown"],                # Exclude tool types
    tool_config_files={                           # Add custom tools
        "custom": "/path/to/custom.json"
    }
)

MCP Server Functions¶

ToolUniverse provides two main MCP server functions for different use cases:

tooluniverse-smcp Function¶

The tooluniverse-smcp function is the main entry point for ToolUniverse’s SMCP server, providing full configurability for different deployment scenarios.

Basic Server Startup¶

Start a basic MCP server with all tools:

# Start server on default port 7000
tooluniverse-smcp

# Start server on specific port
tooluniverse-smcp --port 8000

# Start with custom server name
tooluniverse-smcp --name "My ToolUniverse Server" --port 8000

Hook Configuration¶

Enable intelligent output processing hooks:

# Enable hooks with default SummarizationHook
tooluniverse-smcp --hooks-enabled --port 8000

# Use specific hook type
tooluniverse-smcp --hook-type SummarizationHook --port 8000
tooluniverse-smcp --hook-type FileSaveHook --port 8000

# Use custom hook configuration
tooluniverse-smcp --hook-config-file /path/to/hook_config.json --port 8000

Available Hook Types¶

SummarizationHook: AI-powered summarization of long outputs
FileSaveHook: Save outputs to files with metadata

For detailed hook configuration, see Post-processing Tool Outputs.

Transport Configuration¶

Different transport protocols:

# HTTP transport (default)
tooluniverse-smcp --transport http --port 8000

# STDIO transport (for desktop apps)
tooluniverse-smcp --transport stdio

# Server-Sent Events transport
tooluniverse-smcp --transport sse --port 8000

Category-Based Loading¶

Load only specific tool categories:

# Load specific categories
tooluniverse-smcp --categories uniprot ChEMBL opentarget --port 8000

# Load all except certain categories
tooluniverse-smcp --exclude-categories mcp_auto_loader special_tools --port 8000

Tool-Specific Loading¶

Load specific tools by name:

# Load only specific tools
tooluniverse-smcp --include-tools "UniProt_get_entry_by_accession" "ChEMBL_get_molecule_by_chembl_id" --port 8000

# Load tools from a file
tooluniverse-smcp --tools-file "/path/to/tool_names.txt" --port 8000

Type-Based Filtering¶

Filter by tool types:

# Include only specific tool types
tooluniverse-smcp --include-tool-types "OpenTarget" "ToolFinderEmbedding" --port 8000

# Exclude specific tool types
tooluniverse-smcp --exclude-tool-types "ToolFinderLLM" "Unknown" --port 8000

Server Configuration¶

Advanced server configuration:

# Configure server parameters
tooluniverse-smcp \
    --port 8000 \
    --host 0.0.0.0 \
    --max-workers 10 \
    --transport http \
    --verbose

Discovery Commands¶

List available categories and tools:

# List all available categories
tooluniverse-smcp --list-categories

# List all available tools
tooluniverse-smcp --list-tools

Custom Configuration Files¶

Load additional tool configurations:

# Load custom config files
tooluniverse-smcp --tool-config-files "custom:/path/to/custom_tools.json" --port 8000

tooluniverse-smcp-stdio Function¶

The tooluniverse-smcp-stdio function is specifically designed for stdio transport, making it ideal for Claude Desktop integration and other desktop AI applications. By default, this function enables output processing hooks for intelligent post-processing of tool outputs.

Basic Stdio Server Startup¶

Start a stdio server with default settings (hooks enabled):

# Start stdio server with default SummarizationHook enabled
tooluniverse-smcp-stdio

# Start with specific categories
tooluniverse-smcp-stdio --categories uniprot ChEMBL opentarget

Hook Configuration¶

The stdio server supports intelligent output processing hooks:

# Disable hooks (default is enabled)
tooluniverse-smcp-stdio --no-hooks

# Use FileSaveHook instead of SummarizationHook
tooluniverse-smcp-stdio --hook-type FileSaveHook

# Use custom hook configuration
tooluniverse-smcp-stdio --hook-config-file /path/to/hook_config.json

Available Hook Types¶

SummarizationHook (default): AI-powered summarization of long outputs
FileSaveHook: Save outputs to files with metadata

For detailed hook configuration, see Post-processing Tool Outputs.

️ Practical Examples¶

Research Workflow Setup¶

Setting up for scientific research:

# Python approach
from tooluniverse import ToolUniverse

tu = ToolUniverse()

# Load tools for drug discovery research
tu.load_tools(tool_type=[
    "uniprot",        # Protein information
    "ChEMBL",         # Chemical data
    "opentarget",     # Target-disease associations
    "pubchem",        # Chemical compounds
    "fda_drug_adverse_event"  # Safety data
])

# Ready for research queries
result = tu.run({
    "name": "UniProt_get_entry_by_accession",
    "arguments": {"accession": "P04637"}  # p53 protein
})

# MCP server approach (run_smcp_server)
tooluniverse-smcp \
    --categories uniprot ChEMBL opentarget pubchem fda_drug_adverse_event \
    --port 8000 \
    --name "Drug Discovery Server"

# Or stdio server approach (run_stdio_server) with hooks enabled by default
tooluniverse-smcp-stdio \
    --categories uniprot ChEMBL opentarget pubchem fda_drug_adverse_event \
    --name "Drug Discovery Tools"

# Stdio server with FileSaveHook for data archiving
tooluniverse-smcp-stdio \
    --categories uniprot ChEMBL opentarget pubchem fda_drug_adverse_event \
    --hook-type FileSaveHook \
    --name "Drug Discovery Tools with File Archiving"

️ File Formats¶

Tool Names File Format¶

Create a text file with one tool name per line:

# my_tools.txt - Lines starting with # are comments
OpenTargets_get_associated_targets_by_disease_efoId
Tool_Finder_LLM
ChEMBL_search_similar_molecules

# You can add comments anywhere
Tool_Finder_Keyword