Comprehensive FAQ¶

This page contains detailed answers to frequently asked questions about ToolUniverse.

Tip

Need a quick answer?

For brief answers to the most common questions, see Quick FAQ. This page provides comprehensive information with detailed explanations, troubleshooting tips, and advanced topics.

General Questions¶

What is ToolUniverse?¶

ToolUniverse is a comprehensive collection of scientific tools for Agentic AI, offering integration with various scientific databases and services. It provides a unified interface to access data from FDA, OpenTargets, ChEMBL, PubTator, and many other sources.

Use ToolUniverse as a Python library:

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()

Use ToolUniverse with AI assistants via MCP:

tooluniverse-smcp

Direct tool execution:

tooluniverse-cli run FAERS_count_reactions_by_drug_event

What databases are supported?¶

ToolUniverse integrates with 20+ scientific databases:

Drug Information: FDA FAERS, ChEMBL, PubChem, DrugBank
Gene/Protein Data: UniProt, Ensembl, Human Protein Atlas
Disease Information: OpenTargets, DisGeNET, OMIM
Literature: PubMed, PubTator
Clinical Data: ClinicalTrials.gov, UK Biobank
Pathway Analysis: Enrichr, KEGG, Reactome

Installation & Setup¶

How do I install ToolUniverse?¶

pip install tooluniverse

git clone https://github.com/mims-harvard/ToolUniverse
cd tooluniverse
pip install -e .

pip install tooluniverse[all]

Do I need API keys?¶

Most tools work without API keys! However, some tools require authentication or provide higher rate limits with API keys.

Quick answer:

No API keys needed for most tools (PubMed, UniProt, ChEMBL, OpenTargets, etc.)
Recommended for better performance: NCBI, FDA (3-10x faster rate limits)
Required for specific features: NVIDIA NIM (structure prediction), USPTO (patents), DisGeNET, OMIM

For complete details, see API Keys and Authentication which covers all API keys, how to obtain them, rate limits, and configuration methods.

Common Issues¶

Why am I getting rate limit errors?¶

Many scientific APIs have rate limits. ToolUniverse implements automatic rate limiting, but you may still encounter limits:

# Higher limits with API key
os.environ['NCBI_API_KEY'] = 'your_key'

Use batch processing for multiple queries:

# Process in batches
for batch in batches(gene_list, batch_size=10):
    results = tu.run(batch, use_cache=True, max_workers=8)
    time.sleep(1)  # Add delay between batches

Enable caching to avoid repeated requests:

# Caching is enabled by default
tu = ToolUniverse()
result = tu.run(..., use_cache=True)

Tool returns empty results?¶

Check these common issues:

Correct identifiers: Ensure you’re using the right ID format
API connectivity: Test your internet connection
Service status: Check if the external service is available
Query parameters: Verify your search parameters are valid

# Example: Retrieve UniProt function by accession
query = {
    "name": "UniProt_get_function_by_accession",
    "arguments": {"accession": "P38398"}  # BRCA1 accession
}

MCP Integration¶

How do I use ToolUniverse with Claude?¶

Start MCP Server:
```
tooluniverse-smcp
```

Configure Claude Desktop:

Add to your Claude configuration:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "tooluniverse-smcp-stdio",
      "args": ["--compact-mode"]
    }
  }
}

Test the connection:

Ask Claude: “What tools are available from ToolUniverse?”

Can I use multiple MCP servers?¶

Yes! You can run multiple ToolUniverse instances or combine with other MCP servers:

{
  "mcpServers": {
    "tooluniverse-main": {
      "command": "tooluniverse-smcp",
      "args": ["--port", "3000", "--compact-mode"]
    },
    "tooluniverse-dev": {
      "command": "tooluniverse-smcp",
      "args": ["--port", "3001", "--compact-mode", "--load", "community/dev-tools"]
    }
  }
}

Development¶

How do I add a new tool?¶

Create tool class:

from tooluniverse.base_tool import BaseTool

class MyNewTool(BaseTool):
    def __init__(self):
        super().__init__(
            name="my_new_tool",
            description="Description of what it does"
        )

    def run(self, **kwargs):
        # Implementation here
        return results

Register the tool:

from tooluniverse import ToolRegistry

registry = ToolRegistry()
registry.register_tool(MyNewTool)

Add tests:

def test_my_new_tool():
    tool = MyNewTool()
    result = tool.run(test_parameter="test_value")
    assert result is not None

How do I contribute?¶

Fork the repository
Create a feature branch
Add your changes with tests
Submit a pull request

See our about/contributing Tutorial for detailed instructions.

Performance¶

How can I speed up queries?¶

import os
os.environ["TOOLUNIVERSE_CACHE_DEFAULT_TTL"] = "3600"  # 1 hour
tu = ToolUniverse()
result = tu.run(..., use_cache=True)

# Process multiple queries at once
queries = [
    {"name": "tool1", "arguments": {"id": "1"}},
    {"name": "tool1", "arguments": {"id": "2"}},
]
results = tu.run_batch(queries)

import asyncio

async def main():
    results = await tu.run_async(query)

asyncio.run(main())

Why is the first query slow?¶

The first query often takes longer because:

Tool loading: Tools are loaded on first use
API connection: Initial connection setup
Authentication: API key validation

Subsequent queries will be much faster.

Troubleshooting¶

Getting import errors?¶

Common solutions:

pip install tooluniverse[all]

Ensure Python 3.8+ is installed:

python --version

Use a clean virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows
pip install tooluniverse

Network connectivity issues?¶

Check internet connection
Verify proxy settings if behind corporate firewall

Test specific endpoints:

import requests
response = requests.get('https://platform-api.opentargets.org/api/v4/graphql')
print(response.status_code)

Configure timeouts:
```
tu = ToolUniverse(timeout=30)
```

Still Having Issues?¶

If you can’t find the answer here:

Check the documentation: Tutorial Navigation
Search existing issues: GitHub Issues
Ask the community: Join our Discord server
Report a bug: Create a new GitHub issue with details

Note

When reporting issues, please include:

ToolUniverse version
Python version
Operating system
Full error message
Minimal code example