Setup Tooluniverse

Setup ToolUniverse

Guide the user step-by-step through setting up ToolUniverse.

Agent Behavior

• Detect language from user's first message. Respond in their language; keep commands/URLs in English.
• Go one step at a time. Ask before proceeding.
• Use AskQuestion for structured choices.
• Explain briefly in plain language. Celebrate small wins.
• When something goes wrong, help troubleshoot before moving on.

Internal Notes (do not show)

ToolUniverse has 2,700+ tools. The tooluniverse command enables compact mode automatically, exposing only 5 core MCP tools (list_tools, grep_tools, get_tool_info, execute_tool, find_tools) while keeping all tools accessible via execute_tool.

What is ToolUniverse?

Always explain first, in plain language:

ToolUniverse is free, open-source software connecting to 2,000+ scientific databases (PubMed, UniProt, ChEMBL, FAERS, ClinicalTrials.gov, etc.). Instead of visiting each website, you search from one place. Think of it like a universal remote for scientific databases.

Why AI assistants? The AI reads your question, figures out which databases to search, runs queries, and summarizes results. You just ask your question.

Step 1: Choose How to Use It

Present using AskQuestion:

Options: "I want to ask questions" → Chat mode | "Quick try" → CLI | "I write Python" → SDK | "I don't know" → Recommend Chat mode

If Chat mode, ask which app (AskQuestion): Cursor, Claude Desktop, VS Code/Copilot, Windsurf, Claude Code, Gemini CLI, Codex, Cline/Trae/Antigravity/OpenCode. "I don't have any" → Recommend Claude Desktop.

Step 2: Install uv

Only prerequisite: uv (manages everything else automatically).

Terminal help (if needed): Mac: Cmd+Space → "Terminal" → Enter. Windows: Win key → "PowerShell" → Enter.

curl -LsSf https://astral.sh/uv/install.sh | sh

(This is a safe, standard command that downloads and installs uv, a small package manager. It's widely used by Python developers. Close and reopen your terminal after it finishes.)

Verify: uv --version

CLI Setup

Make sure Step 2 is done, then try:

uvx --from tooluniverse tu status              # How many tools?
uvx --from tooluniverse tu find 'drug safety'  # Search by topic
uvx --from tooluniverse tu info FAERS_count_death_related_by_drug  # See params
uvx --from tooluniverse tu run FAERS_count_death_related_by_drug '{"medicinalproduct": "metformin"}'

First run takes ~30s (downloads package), then instant. Shortcut: uv tool install tooluniverse → then just use tu directly.

All CLI subcommands

Output flags (most commands except build/serve): --json (pretty) or --raw (compact, pipe-friendly).

Continue to Step 3 (API Keys).

SDK Setup

Install `uv` first (Step 2). Do not use system `pip`. On a current Mac (Homebrew Python 3.13/3.14) pip install tooluniverse stops with error: externally-managed-environment (PEP 668), and python3 -m venv can fail at ensurepip. uv avoids both because it downloads and manages its own Python.

uv venv --python 3.12          # own Python + virtualenv, ignores system pip
source .venv/bin/activate      # Windows: .venv\Scripts\activate
uv pip install tooluniverse

uv pip install needs an active virtualenv — run uv venv first, or use uv tool install tooluniverse if you only want the tu command.

For detailed patterns, invoke the tooluniverse-sdk skill.

Optional extras: the base install covers API/database tools. Local ML, cheminformatics, and plotting tools need extras — uv pip install 'tooluniverse[ml]', [visualization], [bioinformatics], or [all]. Run tooluniverse-doctor to see which groups you are missing. Note [all] does not include singlecell, smolagents, client, or build; install those separately.

Coding API — 3 calling patterns

Pattern 1: Direct import (typed, with autocomplete):

from tooluniverse.tools import UniProt_get_entry_by_accession
result = UniProt_get_entry_by_accession(accession="P12345")

Pattern 2: Attribute access (no import needed per tool):

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()
result = tu.tools.UniProt_get_entry_by_accession(accession="P12345")

Pattern 3: JSON-based (dynamic, for pipelines):

result = tu.run({"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P12345"}})

Generate typed wrappers: tu build (creates importable Python modules with autocomplete).

Agentic Tools & Code Executor

ToolUniverse also includes 23 AI-powered agentic tools (ScientificTextSummarizer, HypothesisGenerator, ExperimentalDesignScorer, peer-review tools, etc.) and 2 code executor tools (python_code_executor, python_script_runner). These are called like any other tool — via tu.run() or execute_tool(). Agentic tools require an LLM API key (e.g., OPENAI_API_KEY).

Continue to Step 3 (API Keys).

MCP Setup (Chat Mode)

Offer the two low-effort paths first. Editing JSON by hand is the fallback, not the recommendation — a mistyped comma is the single most common setup failure. Only walk through the manual path if neither option below fits.

Path A — let an AI agent do it. If the user already has any agent (Claude, Cursor, Copilot, Gemini, Codex...), they can paste this into it:

Read https://aiscientist.tools/setup.md and set up ToolUniverse for me.

The agent handles config, keys, skills, and validation. No terminal, no JSON.

Path B — Claude Code or Codex users: one-liner, no config file at all.

Claude Code:

claude plugin marketplace add mims-harvard/ToolUniverse
claude plugin install tooluniverse@tooluniverse

See the tooluniverse-claude-code-plugin skill's "Recommended: turn on auto-update" step so future releases apply without manual claude plugin update.

Codex:

codex plugin marketplace add mims-harvard/ToolUniverse
codex plugin add tooluniverse -m tooluniverse

See the tooluniverse-codex-plugin skill for verification, updates, and troubleshooting.

Both install the MCP server plus 180+ skills in one step. Google Antigravity users: see the tooluniverse-antigravity-plugin skill instead — its install flow differs (agy plugin install, not a marketplace add).

Manual config (fallback)

Make sure Step 2 is done (uv --version works).