tooluniverse-literature-deep-research
Deep literature review — PubMed, EuropePMC, bioRxiv preprints, citation networks, evidence synthesis. Disambiguates queries, runs collision-aware searches, grades evidence T1-T4, and produces structured reports. Use for systematic literature review, meta-analysis evidence collection, and detailed an
By mims-harvard · 646 installs
npx skills add mims-harvard/tooluniverse --skill tooluniverse-literature-deep-research
Source repository · Upstream listing
Literature Deep Research
Systematic literature research: disambiguate, search with collision aware queries, grade evidence, produce structured reports.
KEY PRINCIPLES : (1) Disambiguate first (2) Right size deliverable (3) Grade every claim T1 T4 (4) All sections mandatory even if "limited evidence" (5) Source attribution for every claim (6) English first queries, respond in user's language (7) Report = deliverable, not search log
LOOK UP, DON'T GUESS
Search PubMed/EuropePMC FIRST before reasoning. A published paper beats memory.
Factoid search strategy:
1. Extract KEY TERMS (most specific nouns/verbs)
2. EuropePMC search articles(query="term1 term2 term3", limit=5)
3. No results BROADEN (remove most restrictive term)
4. Too many NARROW (add specific terms)
5. Answer usually in abstract of top results
6. Failed query try DIFFERENT TERMS/synonyms, don't repeat
COMPUTE, DON'T DESCRIBE
When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.
Workflow
Phase 0: Mode Selection
Mode When Deliverable
Factoid Single concrete question 1 page fact check report + bibliography
Mini review Narrow topic 1 3 page narrative
Full Deep Research Comprehensive overview 15 section report + bibliography
Factoid Mode (Fast Path)
Domain Detection
Pattern Domain Action
Gene/protein symbol Biological target Full bio disambiguation
Drug name Drug Drug disambiguation (1.5)
Disease name Disease Disease disambiguation (1.6)
CS/ML topic General academic Skip bio tools, literature only
Cross domain Interdisciplinary Resolve each entity in its domain
Cross Skill Delegation
Gene/protein deep dive: tooluniverse target research
Drug profile: tooluniverse drug research
Disease profile: tooluniverse disease research
Use this skill for literature synthesis . Use specialized skills for entity profiling . For max depth, run both.
Phase 1: Subject Disambiguation + Profile
1.1 Biological Target Resolution
1.2 Naming Collision Detection
Check first 20 results. If 20% off topic, build negative filter: NOT [collision1] NOT [collision2] .
Gene family: "ADAR" NOT "ADAR2" NOT "ADARB1" . Cross domain: add context terms.
1.3 Baseline Profile (Bio Targets)
GPCR targets: delegate to tooluniverse target research .
1.5 Drug Disambiguation
Identity : OpenTargets get drug chembId by generic name , ChEMBL get drug , PubChem get CID by compound name , drugbank get drug basic info by drug name or id
Targets : ChEMBL get drug mechanisms , OpenTargets get associated targets by drug chemblId , DGIdb get drug gene interactions
Safety : OpenTargets get drug adverse events by chemblId , OpenTargets get drug indications by chemblId , search clinical trials
1.6 Disease Disambiguation
1.7 Compound Queries (e.g., "metformin in breast cancer")
Resolve both entities, then cross reference via CTD get chemical gene interactions, CTD get chemical diseases, OpenTargets drug target/drug disease tools. Intersect shared targets/pathways.
1.8 General Academic / 1.9 Interdisciplinary
Non bio: skip bio tools, use ArXiv/DBLP/OSF. Cross domain: resolve bio entities with 1.1 1.3, search CS/general in parallel, merge and cross reference.
Phase 2: Literature Search
Methodology stays internal. Report shows findings, not process.
2.1 Query Strategy
Step 1: Seeds (15 30 core papers): domain specific title searches with date/sort filters.
Step 2: Citation expansion : PubMed get cited by , EuropePMC get citations/references , PubMed get related , SemanticScholar get recommendations , OpenCitations get citations . If the opt in Noodle MCP is connected ( noodle , needs NOODLE MCP URL ), its bounded citation/semantic graph traversal is another angle on the same PubMed corpus a discovery signal, not evidence of causality or validity, same caveat as the others.
Step 3: Collision filtered broader queries : "[TERM]" AND ([context]) NOT [collision]
2.2 Literature Tools — core set + adaptive by domain
Run the core multi field set on every review (catches what any single index misses), then add the domain rows that match the subject. Don't fire every source blindly — 6–10 well chosen indexes beat 20 noisy ones.
ALWAYS run (core, all disciplines) : PubMed search articles , EuropePMC search articles , openalex search works (query param search / query ) or openalex literature search (query param search keywords ) — pick one and match its param; mixing them silently returns off topic results — and SemanticScholar search papers
Then add by domain:
Domain Add these Notes
Biomedical / clinical PMC search papers (full text), PubTator3 LiteratureSearch (entity & relations: queries), PubMed Guidelines Search (clinical guidelines) PubTator normalizes gene/drug/disease entities
Biology (ecology/evolution/plant) EuropePMC as PRIMARY + OpenAlex PubMed returns 0–1 for non clinical biology
CS / ML / AI ArXiv search papers , DBLP search publications arXiv + CS bibliography
Physics / HEP / astro InspireHEP search papers 1.6M+ particle/astro records
Broad / hard to find / OA Crossref search works , CORE search papers , DOAJ search articles , Fatcat search scholar , Consensus search papers DOI registry + OA aggregators + Internet Archive Scholar; Consensus (220M+ papers) adds an AI takeaway + study design metadata per paper useful for fast triage, not a substitute for reading the source
Regional / EU funded OpenAIRE search publications , HAL search archive EU open science + French national archive
Datasets / software / outputs Figshare search articles , Zenodo search records Citable DOIs for data & code
Preprints (latest) EuropePMC search articles(source='PPR') , OSF search preprints , BioRxiv get preprint / MedRxiv get preprint (DOI lookup) bioRxiv/medRxiv/PsyArXiv etc.
Multi source : advanced literature search agent (12+ DBs; needs Azure key fallback: query the core set individually).
Citation impact : iCite search publications (RCR/APT), iCite get publications (by PMID), scite get tallies (support/contradict). PubMed only; for CS use SemanticScholar.
Identifiers and reference lists : PubMed convert article ids {"ids": ["23193287", "10.1093/nar/gks1195"]} converts between PMID, PMCID and DOI (auto detected; only articles in PubMed Central convert, others return found: false ) use it to turn a DOI into the PMCID that EuropePMC get full text needs. PubMed lookup article by citation {"journal": "Nature", "year": 2015, "volume": 521, "first page": 436, "author": "lecun y"} resolves a reference list entry to a PMID ( status : found / ambiguous / not found; pass citations for a batch). The match is exact on the fields given, so an unfound citation is a signal to re check the fields, not proof the paper is missing.
A domain specific index returning 0 (e.g. ArXiv on a pure clinical topic) is normal — only worry if the whole core set is empty.
2.3 2.4 Full Text & PubMed Zero Result Fallback
Full text: see FULLTEXT STRATEGY.md for three tier strategy.
CRITICAL : PubMed returns 0 for ~30% of valid queries. Always retry with EuropePMC when PubMed returns empty. This is not optional.
2.5 Tool Failure / OA Handling
Retry once fallback tool. Key fallbacks: PubMed get cited by EuropePMC get citations OpenCitations. OA: Unpaywall if configured, else Europe PMC/PMC/OpenAlex flags.
Last resort when every structured index above is empty (a brand new preprint, a dataset page, a project site with no DOI): the opt in exa tools (general neural web search, no key needed for casual use) can still find it, but it's general internet retrieval, not a scientific database verify anything it surfaces against a real source before citing, don't grade it T1 T4 as if it were literature.
2.6 Controlled Vocabulary, Text Mined Annotations, Citation Cross References, and Variant Literature
Four small tool families beyond core search/citation coverage — verified live, not schema assumed:
MeSH (controlled vocabulary) : MeSH search descriptors / MeSH search terms resolve a free text term to NLM's standardized MeSH descriptor/entry term IDs; MeSH get descriptor returns the descriptor's official label, type, and annotation. Use to broaden or standardize a query before searching (e.g. a user says "sugar disease" MeSH search terms finds the descriptor is actually filed under "Diabetes Mellitus") or to confirm two different sounding search hits are actually indexed under the same concept.
EuroPMCAnnot (text mined entity annotations) : EuroPMCAnnot get article annotations (all entity mentions in one article: genes, diseases, chemicals, organisms, etc.), EuroPMCAnnot get chemicals from article (chemical/compound mentions only, a filtered convenience view), EuroPMCAnnot get annotations by type (one annotation type across multiple articles at once). These extract what a paper mentions without you reading the full text — useful for a fast relevance check across many candidate papers, or for confirming a specific gene/chemical is actually discussed (not just present in an abstract keyword match). Live verified example: EuroPMCAnnot get chemicals from article on PMC4353746 returned 19 real chemical mentions including "Resistin".
Citation cross references — naming collision, read carefully : src/tooluniverse/data/europepmc citations tools.json defines EPMC get citations , EPMC get references , and EuropePMC get article datalinks — do NOT confuse these with the already documented EuropePMC get citations / EuropePMC get references (core europe pmc tools.json , used above in Phase 2.1/TOOL NAMES REFERENCE.md). They are separate implementations with near identical names hitting the same underlying Europe PMC REST endpoints. Live verified as of this writing: the /references endpoint is down on BOTH implementations ( EPMC get references and EuropePMC get references both return a real 503 "This API is temporarily unavailable due to maintenance" from www.ebi.ac.uk ), and EuropePMC get article datalinks independently confirmed broken via direct curl (33s response, HTTP 500). EPMC get citations / EuropePMC get citations (the forward citation direction) both work normally. Practical guidance : prefer the already documented EuropePMC get citations / EuropePMC get references names for citation work; if references fetching fails with a 503, it is very likely this live outage, not a query problem — say so rather than reporting "no references found." EuropePMC get article datalinks (when working) additionally surfaces what data/database records a paper deposited (GenBank accessions, PDB entries, clinical trial registrations) — complementary to, not a replacement for, citations/references.
Document conversion (any format to markdown) : convert to markdown {"uri": "..."} accepts an http: / https: / file: / data: URI and converts it to markdown — verified live on an HTML page. Reach for this when a source is a PDF, DOCX, PPTX, XLSX, or HTML page rather than something the literature tools above already return as structured JSON (e.g. a supplementary materials file, an institutional report, a non indexed working paper someone hands you a link to) and you need its actual text content, not just metadata. This is a generic conversion utility, not a literature search tool — use PubMed/EuropePMC/OpenAlex above whenever the source is already indexed there.
BGPT (structured critical appraisal search) : BGPT search paper evidence is a literature search