FAQ - Frequently Asked Questions¶

This page contains answers to the most frequently asked questions about ToolUniverse.

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:

python -m tooluniverse.smcp_server

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/zitniklab/tooluniverse
cd tooluniverse
pip install -e .

pip install tooluniverse[all]

Do I need API keys?¶

Some tools require API keys for accessing external services:

Required API Keys: - OpenTargets Platform API key (free registration) - NCBI E-utilities API key (optional but recommended)

How to set API keys:

import os
os.environ['OPENTARGETS_API_KEY'] = 'your_api_key_here'
os.environ['NCBI_API_KEY'] = 'your_ncbi_key_here'

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(batch)
    time.sleep(1)  # Add delay between batches

Enable caching to avoid repeated requests:

tu = ToolUniverse(enable_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: Check if gene symbol is valid
query = {
    "name": "UniProt_get_protein_info",
    "arguments": {"gene_symbol": "BRCA1"}  # Use standard gene symbol
}

MCP Integration¶

How do I use ToolUniverse with Claude?¶

Start MCP Server:
```
python -m tooluniverse.smcp_server
```

Configure Claude Desktop:

Add to your Claude configuration:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "python",
      "args": ["-m", "tooluniverse.smcp_server"]
    }
  }
}

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": "python",
      "args": ["-m", "tooluniverse.smcp_server", "--port", "3000"]
    },
    "tooluniverse-dev": {
      "command": "python",
      "args": ["-m", "tooluniverse.smcp_server", "--port", "3001", "--config", "dev"]
    }
  }
}

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?¶

tu = ToolUniverse(enable_cache=True, cache_ttl=3600)

# 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: user_guide/index
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