CtrlK
BlogDocsLog inGet started
Tessl Logo

tooluniverse-sdk

Build AI scientist systems with the ToolUniverse Python SDK for scientific research. Covers the 3 calling patterns (`tu.run` portable dict API, `tu.tools.X` function API, direct class instantiation), tool loading, batch execution, MCP server integration, and embedding-based tool search. Use for SDK programming, custom tool composition, benchmarking pipelines, and integrating ToolUniverse into research workflows.

The canonical home for this skill is tooluniverse-sdk in mims-harvard/ToolUniverse

SKILL.md
Quality
Evals
Security

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

pip install tooluniverse              # Standard
pip install tooluniverse[embedding]   # Embedding search (GPU)
pip install tooluniverse[all]         # All features
export OPENAI_API_KEY="sk-..."  # Required for LLM tool search
export NCBI_API_KEY="..."       # Optional

Quick Start

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

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

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

# 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

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

CategoryToolsUse Cases
ProteinsUniProt, RCSB PDB, AlphaFoldProtein analysis, structure
DrugsDrugBank, ChEMBL, PubChemDrug discovery, compounds
GenomicsEnsembl, NCBI Gene, gnomADGene analysis, variants
DiseasesOpenTargets, ClinVarDisease-target associations
LiteraturePubMed, Europe PMCLiterature search
ML ModelsADMET-AI, AlphaFoldPredictions, modeling
PathwaysKEGG, ReactomePathway analysis

Resources

  • Docs: https://zitniklab.hms.harvard.edu/ToolUniverse/
  • GitHub: https://github.com/mims-harvard/ToolUniverse
  • See REFERENCE.md for detailed guides.
Repository
mims-harvard/ToolUniverse
Path

plugins/tooluniverse/skills/tooluniverse-sdk/SKILL.md

Commit

089eb8e

Last updated
First committed

Canonical home

mims-harvard/ToolUniverse
In sync

since Jul 28, 2026

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill