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_quick_reference for commonly used classes and methods, or ../api_comprehensive for full API reference.

tooluniverse.execute_function.ToolUniverse.load_tools(self, 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)

Loads tool definitions from JSON files into the instance’s tool registry.

If tool_type is None, loads all available tool categories from self.tool_files. Otherwise, loads only the specified tool categories.

After loading, deduplicates tools by their ‘name’ field and updates the internal tool list. Also refreshes the tool name and description mapping.

Parameters:

  • tool_type (list, optional) – List of tool category names to load. If None, loads all categories.

  • exclude_tools (list, optional) – List of specific tool names to exclude from loading.

  • exclude_categories (list, optional) – List of tool categories to exclude from loading.

  • include_tools (list or str, optional) – List of specific tool names to include, or path to a text file containing tool names (one per line). If provided, only these tools will be loaded regardless of categories.

  • tool_config_files (dict, optional) – Additional tool configuration files to load. Format: {“category_name”: “/path/to/config.json”}

  • tools_file (str, optional) – Path to a text file containing tool names to include (one per line). Alternative to include_tools when providing a file path.

  • include_tool_types (list, optional) – List of tool types to include (e.g., [“OpenTarget”, “ChEMBLTool”]). If provided, only tools with these types will be loaded.

  • exclude_tool_types (list, optional) – List of tool types to exclude (e.g., [“ToolFinderEmbedding”]). Tools with these types will be excluded.

Side Effects:

  • Updates self.all_tools with loaded and deduplicated tools.

  • Updates self.tool_category_dicts with loaded tools per category.

  • Calls self.refresh_tool_name_desc() to update tool name/description mapping.

  • Prints the number of tools before and after loading.

Examples

# Load specific tools by name tu.load_tools(include_tools=[“UniProt_get_entry_by_accession”, “ChEMBL_get_molecule_by_chembl_id”])

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

# 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”])

# Load additional config files tu.load_tools(tool_config_files={“custom_tools”: “/path/to/custom_tools.json”})

# Combine multiple options tu.load_tools(

tool_type=[“uniprot”, “ChEMBL”], exclude_tools=[“problematic_tool”], exclude_tool_types=[“Unknown”], tool_config_files={“custom”: “/path/to/custom.json”}

)

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:

  1. `tooluniverse-mcp` - Full-featured server with configurable transport (HTTP, SSE, stdio)

  2. `tooluniverse-smcp-stdio` - Specialized server for stdio transport (for desktop AI applications)

Both functions expose the same 600+ scientific tools through the Model Context Protocol (MCP), but with different transport configurations and argument handling.

tooluniverse-mcp Function¶

The tooluniverse-mcp 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