---
id: mims-harvard/ToolUniverse/tooluniverse-sdk
version: "9b4f9ca4"
license: Apache-2.0
install: manual
updated: 2026-07-27
---

# tooluniverse-sdk — ToolUniverse SDK provides a Python interface to compose and execute scientific research pipelines across protein analysis, drug discovery, genomics, and disease databases. Call tools via portable dict API, function methods, or direct instantiation, with batch execution and caching for reproducible workflows.

Publisher: mims-harvard · Stars: 1595 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/mims-harvard/ToolUniverse`

## SKILL.md

# ToolUniverse Python SDK

**3 calling patterns -- start with pattern 1:**
1. `tu.run({"name": ..., "arguments": ...})` -- single tool call, dict API (most portable)
2. `tu.tools.ToolName(param=value)` -- function API (recommended for interactive use)
3. Direct class instantiation -- advanced, bypasses caching/hooks

## Installation

```bash
pip install tooluniverse              # Standard
pip install tooluniverse[embedding]   # Embedding search (GPU)
pip install tooluniverse[all]         # All features
```

```bash
export OPENAI_API_KEY="sk-..."  # Required for LLM tool search
export NCBI_API_KEY="..."       # Optional
```

## Quick Start

```python
from tooluniverse import ToolUniverse

tu = ToolUniverse()
tu.load_tools()  # REQUIRED before any tool call

# Find tools
tools = tu.run({"name": "Tool_Finder_Keyword", "arguments": {"description": "protein structure", "limit": 10}})

# Execute (dict API)
result = tu.run({"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P05067"}})

# Execute (function API)
result = tu.tools.UniProt_get_entry_by_accession(accession="P05067")
```

## Core Patterns

### Batch Execution

```python
calls = [
    {"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P05067"}},
    {"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P12345"}},
]
results = tu.run_batch(calls)
```

### Scientific Workflow

```python
def drug_discovery_pipeline(disease_id):
    tu = ToolUniverse(use_cache=True)
    tu.load_tools()
    try:
        targets = tu.tools.OpenTargets_get_associated_targets_by_disease_efoId(efoId=disease_id)
        compound_calls = [
            {"name": "ChEMBL_search_molecule_by_target",
             "arguments": {"target_id": t['id'], "limit": 10}}
            for t in targets['data'][:5]
        ]
        compounds = tu.run_batch(compound_calls)
        return {"targets": targets, "compounds": compounds}
    finally:
        tu.close()
```

## Configuration

```python
# Caching
tu = ToolUniverse(use_cache=True)
stats = tu.get_cache_stats()
tu.clear_cache()

# Hooks (auto-summarization of large outputs)
tu = ToolUniverse(hooks_enabled=True)

# Load specific categories
tu.load_tools(categories=["proteins", "drugs"])
```

## Critical Notes

1. **Always call `load_tools()`** before using any tools
2. **Tool Finder returns nested structure**: access via `tools['tools']` after `isinstance(tools, dict)` check
3. **Tool names are case-sensitive**: `UniProt_get_entry_by_accession` not `uniprot_get_...`
4. **Check required params**: `tu.all_tool_dict["ToolName"]['parameter'].get('required', [])`
5. **Cache deterministic calls** (ML predictions, DB queries); don't cache real-time data

## Error Handling

```python
from tooluniverse.exceptions import ToolError, ToolUnavailableError, ToolValidationError

try:
    result = tu.tools.some_tool(param="value")
except ToolUnavailableError:
    ...  # Tool service down
except ToolValidationError as e:
    tool_info = tu.all_tool_dict["some_tool"]
    print(f"Required: {tool_info['parameter'].get('required', [])}")
```

## Tool Categories

| Category | Tools | Use Cases |
|----------|-------|-----------|
| Proteins | UniProt, RCSB PDB, AlphaFold | Protein analysis, structure |
| Drugs | DrugBank, ChEMBL, PubChem | Drug discovery, compounds |
| Genomics | Ensembl, NCBI Gene, gnomAD | Gene analysis, variants |
| Diseases | OpenTargets, ClinVar | Disease-target associations |
| Literature | PubMed, Europe PMC | Literature search |
| ML Models | ADMET-AI, AlphaFold | Predictions, modeling |
| Pathways | KEGG, Reactome | Pathway analysis |

## Resources

- **Docs**: https://zitniklab.hms.harvard.edu/ToolUniverse/
- **GitHub**: https://github.com/mims-harvard/ToolUniverse
- See [REFERENCE.md](REFERENCE.md) for detailed guides.


[View on SkillFed](https://skillfed.io/mims-harvard/ToolUniverse/tooluniverse-sdk) · [View on GitHub](https://github.com/mims-harvard/ToolUniverse)