Getting Started with ToolUniverse

This tutorial provides detailed, step-by-step instructions for using ToolUniverse effectively.

Prerequisites: You should have already completed the Quick Start Tutorial and have ToolUniverse installed (see Installation). This tutorial assumes basic Python knowledge and internet access for API calls.

🧪 Step-by-Step Tutorial

Understanding Basic Workflow

ToolUniverse follows a simple but powerful pattern:

  1. Initialize once: Create a ToolUniverse instance

  2. Load tools: Load available tools from various databases

  3. Query tools: Use standardized query format

  4. Get results: Receive structured data

See also

For full AI-Tool Interaction Protocol, see AI-Tool Interaction Protocol

Let’s start with a simple example and build up complexity:

Step 1: Initialize ToolUniverse

Create a ToolUniverse instance and load scientific tools. This step sets up the foundation for accessing 600+ tools across various scientific domains.

from tooluniverse import ToolUniverse

# Initialize ToolUniverse
tu = ToolUniverse()

# Load all tools
print("Loading scientific tools...")
tu.load_tools()

print(f"✅ Loaded {len(tu.all_tools)} scientific tools!")

See also

For detailed tool loading options and configurations, see Tool Loading Tutorial

Step 2: Explore Available Tools

List built-in tools in ToolUniverse: This method supports two different organization modes to help you understand tools from different perspectives.

# organize by config file categories
stats = tu.list_built_in_tools(mode='config')
# or organize by tool types
stats = tu.list_built_in_tools(mode='type')

See also

For comprehensive tool listing methods, see Tool Listing Tutorial

To find tools by description, use the Find Tool operation. This feature helps you or your AI scientists discover relevant tools based on their descriptions. We support three search methods: keyword search, LLM-based search, and embedding search.

# Search for specific tools
protein_tools = tu.run({
    "name": "Tool_Finder_Keyword", # or Tool_Finder_LLM (LLM-API based) or Tool_Finder (Embedding-based)
    "arguments": {
        "query": "protein structure",
        "limit": 5
    }
})
print(f"Found {len(protein_tools)} protein-related tools")

See also

For comprehensive tool search methods, see guide/finding_tools

Step 3: Load Tool Specifications

Inspect tool specifications to understand their parameters and capabilities before execution. This helps you or your AI scientists understand what arguments each tool expects and how to use them effectively.

# Get tool specification by name
spec = tu.tool_specification("UniProt_get_protein_info")
print("Tool specification:")
print(f"Name: {spec['name']}")
print(f"Description: {spec['description']}")
print("Parameters:")
for param_name, param_info in spec['parameters']['properties'].items():
    print(f"  - {param_name}: {param_info['type']} - {param_info['description']}")

# Get multiple tool specifications
specs = tu.get_tool_specification_by_names([
    "FAERS_count_reactions_by_drug_event",
    "OpenTargets_get_associated_targets_by_disease_efoId"
])
print(specs)

See also

For detailed tool specification schema and interaction protocols, see AI-Tool Interaction Protocol

Step 4: Execute Tools

Execute scientific tools using the standardized query format. All tools follow a consistent structure that makes it easy to work with different scientific databases and APIs.

All tools follow this consistent structure:

# Standardized tool execution across all 600+ tools
query = {
    "name": "action_description",  # Tool identifier
    "arguments": {                 # Tool parameters
        "parameter1": "value1",
        "parameter2": "value2"
    }
}

result = tu.run(query)

See also

For detailed tool execution patterns and advanced usage, see Tool Caller Tutorial

Execute your First Scientific Tool Call

Run your scientific tool call to use tools. This demonstrates how to access drug safety, gene information, literature, and disease data through standardized tool calls.

Retrieve comprehensive protein and gene information from UniProt database. Get protein sequences, functions, annotations, and related biological data.

# Get comprehensive gene information
gene_query = {
    "name": "UniProt_get_protein_info",
    "arguments": {"gene_symbol": "BRCA1"}
}
gene_info = tu.run(gene_query)
print(gene_info)

Analyze drug safety profiles using FDA adverse event reporting data. Identify potential side effects and safety concerns for pharmaceutical compounds.

# Check drug adverse events
safety_query = {
    "name": "FAERS_count_reactions_by_drug_event",
    "arguments": {"medicinalproduct": "aspirin"}
}
safety_data = tu.run(safety_query)
print(safety_data)

Explore disease-target relationships using OpenTargets platform. Discover therapeutic targets associated with specific diseases and their evidence scores.

# Find targets associated with a disease
disease_query = {
    "name": "OpenTargets_get_associated_targets_by_disease_efoId",
    "arguments": {"efoId": "EFO_0000685"}  # Rheumatoid arthritis
}
targets = tu.run(disease_query)

print(targets)

Search scientific literature across multiple databases with entity recognition. Find relevant papers, abstracts, and citations for your research topics.

# Search scientific literature
literature_query = {
    "name": "PubTator_search_publications",
    "arguments": {
        "query": "CRISPR cancer therapy",
        "limit": 10
    }
}
papers = tu.run(literature_query)

print(papers)

See also

ToolUniverse support the building of complex scientific workflows. For advanced workflow patterns and tool composition, see Scientific Workflows

MCP Server Integration

Connect ToolUniverse to AI assistants through the Model Context Protocol (MCP). This enables AI agents to discover and execute scientific tools automatically, creating powerful AI-scientist workflows.

# Start ToolUniverse MCP server with HTTP transport
tooluniverse-smcp

# Start ToolUniverse MCP server with STDIO transport
tooluniverse-smcp-stdio

# Python MCP server setup
from tooluniverse.smcp import SMCP

# Create MCP server
server = SMCP(
    name="Scientific Research Server",
    tool_categories=["uniprot", "opentarget", "ChEMBL"],
    search_enabled=True
)

# Start server
server.run_simple(transport="http", host="localhost", port=8000)

See also

For complete MCP server setup, configuration, and integration, see MCP Support

See also

For complete MCP integration with LLMs/Reasoning models/AI Agents like Claude, ChatGPT, Gemini, and Qwen, see Building AI Scientists

ToolUniverse Features

💡 For Python API documentation, see the dedicated tooluniverse section.

📖 Building AI Scientists

  • Building AI Scientists Overview → Building AI Scientists - Transform any LLM into a powerful research scientist

    • Claude Desktop → Claude Desktop - Integrate ToolUniverse with Claude Desktop App through MCP

    • Claude Code → Claude Code - Build AI scientists using Claude Code environment

    • Gemini CLI → Gemini CLI - Command-line based scientific research with Gemini CLI

    • Qwen Code → Qwen Code - AI scientist integration with Qwen Code environment

    • Codex CLI → GPT Codex CLI - Terminal-based AI scientist with Codex CLI

    • ChatGPT API → ChatGPT API - Programmatic scientific research with ChatGPT function calling

Tools

  • Tools Configuration Index → Available Tools - Complete index of all available tools

  • Remote Tools Setup → Remote Tools Setup - Setup and configuration for remote tools

📖 Use ToolUniverse

  • Guide Overview → Tutorial Navigation - Comprehensive guide to using ToolUniverse

  • Interaction Protocol → AI-Tool Interaction Protocol - AI-Tool interaction standards and protocols

  • Loading Tools → Tool Loading Tutorial - Complete tutorial to loading tools with Python API and MCP terminal commands

  • Listing Tools → Tool Listing Tutorial - Discover and filter tools by capability, domain, and IO

  • Tool Discovery → Tool Finder Tutorial - Tutorial to ToolUniverse’s three tool finder methods: keyword, LLM, and embedding search

  • Tool Caller → Tool Caller Tutorial - Primary execution engine with dynamic loading, validation, and MCP server integration

  • Case Study → Case Study: Hypercholesterolemia Drug Discovery - End-to-end hypercholesterolemia drug discovery workflow with Gemini 2.5 Pro

  • Agentic Tools → Agentic Tools Tutorial - Build and use AI-powered tools with LLMs for tasks requiring reasoning and creativity

  • Tool Composition → Tool Composition Tutorial - Chain ToolUniverse’s 600+ tools into powerful scientific workflows using Tool Composer

  • Scientific Workflows → Scientific Workflows - Real-world research scenarios: drug discovery, safety analysis, literature review

  • Expert Feedback → Human Expert Feedback - Human-in-the-loop consultation platform for AI systems with web interface

  • Embedding Store Guide → tool_setup_guides/Embedding_store_guide - Setup and configuration for embedding storage

  • Hooks System → Post-processing Tool Outputs - Intelligent output processing with AI-powered hooks

🛠️ Expand ToolUniverse

📚 API & Reference

  • API Modules → tooluniverse - Complete API reference documentation

  • Reference Index → Reference - Reference documentation and specifications

  • Help & Support → Help & Support - Help resources and troubleshooting guides

See also

For complete tool reference and capabilities, see Available Tools Reference