mims-harvard/tooluniverse/tooluniverse-sequence-retrieval

Biological Sequence Retrieval

Retrieve DNA, RNA, and protein sequences with proper disambiguation and cross-database handling.

IMPORTANT: Always use English terms in tool calls. Only try original-language terms as fallback. Respond in the user's language.

LOOK UP DON'T GUESS: Never assume accession numbers or sequence versions. Always retrieve and verify from NCBI or ENA.

Domain Reasoning

Sequence quality hierarchy: RefSeq (NM_/NP_ = curated) > RefSeq predicted (XM_/XP_) > GenBank (submitted). Prefer the MANE Select transcript for human canonical isoforms. Check version numbers -- annotations improve across versions.

Workflow

Phase 0: Clarify (if needed) → Phase 1: Disambiguate Gene/Organism → Phase 2: Search & Retrieve → Phase 3: Report

Phase 0: Clarification (When Needed)

Ask ONLY if: gene exists in multiple organisms, sequence type unclear, or strain matters. Skip for: specific accessions, clear organism+gene combos, complete genome requests with organism.

Phase 1: Gene/Organism Disambiguation

Accession Type Decision Tree

CRITICAL: Never try ENA tools with RefSeq accessions -- they return 404.

Identity Checklist

• Organism confirmed (scientific name)
• Gene symbol/name identified
• Sequence type determined (genomic/mRNA/protein)
• Accession prefix identified for tool selection

Phase 2: Data Retrieval (Internal)

Retrieve silently. Do NOT narrate the search process.

# Search NCBI Nucleotide
result = tu.tools.NCBI_search_nucleotide(
    operation="search", organism=organism, gene=gene,
    strain=strain, keywords=keywords, seq_type=seq_type, limit=10
)
# Get accessions from UIDs
accessions = tu.tools.NCBI_fetch_accessions(operation="fetch_accession", uids=result["data"]["uids"])
# Retrieve sequence (FASTA or GenBank format)
sequence = tu.tools.NCBI_get_sequence(operation="fetch_sequence", accession=accession, format="fasta")
# ENA alternative (non-RefSeq accessions only)
entry = tu.tools.ena_get_entry(accession=accession)
fasta = tu.tools.ena_get_sequence_fasta(accession=accession)

Fallback Chains

Phase 3: Report Sequence Profile

Present as a Sequence Profile Report. Hide search process. Include:

1. Search Summary: query, database, result count
2. Primary Sequence: accession, type (RefSeq/GenBank), organism, strain, length, molecule, topology, curation level
3. Sequence Preview: first lines of FASTA (truncated)
4. Annotations Summary: CDS/tRNA/rRNA/regulatory feature counts (from GenBank format)
5. Alternative Sequences: ranked by relevance and curation, with ENA compatibility
6. Cross-Database References: RefSeq, GenBank, ENA/EMBL, BioProject, BioSample
7. Download Options: FASTA (for BLAST/alignment), GenBank (for annotation)

Curation Level Tiers

Reasoning Framework

Sequence quality: Prefer RefSeq over GenBank. Check version numbers. Sequences with "PREDICTED" in definition are not experimentally validated.

Accession guidance: RefSeq = NCBI-only. GenBank = mirrored in ENA/EMBL. Default to RefSeq mRNA (NM_) for human/model organisms; most complete genome assembly for microbial queries.

Cross-database reconciliation: Same sequence may have different accessions (e.g., GenBank U00096 = RefSeq NC_000913 for E. coli K-12). Always report both when available. Discrepancies between GenBank/RefSeq typically indicate RefSeq curation corrected submission errors.

Synthesis Questions

1. What is the highest-quality accession available?
2. Are there alternative accessions in other databases?
3. What is the annotation completeness?
4. Is the sequence from the expected organism/strain?
5. What download format suits the user's downstream analysis?

Error Handling

Tool Reference

NCBI Tools: NCBI_search_nucleotide (search), NCBI_fetch_accessions (UID→accession), NCBI_get_sequence (retrieve) ENA Tools (GenBank/EMBL only): ena_get_entry (metadata), ena_get_sequence_fasta (FASTA), ena_get_entry_summary (summary)

Search Parameters Reference

NCBI_search_nucleotide: operation="search", organism (scientific name), gene (symbol), strain, keywords, seq_type (complete_genome/mrna/refseq), limit

NCBI_get_sequence: operation="fetch_sequence", accession, format (fasta/genbank)

Whole-Organism Reference Proteomes (UniProt)

A different granularity from Phases 1-3 above: src/tooluniverse/data/uniprot_ref_tools.json's UniProtRef_search_proteomes/UniProtRef_get_proteome (no API key required) return organism-LEVEL proteome metadata — total protein count, chromosome/component breakdown, genome accession — not one sequence. Reach for these when the question is "what is species X's reference proteome and how big is it" (e.g. before a proteome-wide analysis, or to find the right genome-assembly accession to hand to Phase 2 above), not for fetching an individual gene/transcript sequence.

Real example chain (verified live): UniProtRef_search_proteomes {"query": "SARS-CoV-2"} -> 3 results, including UP000464024 (proteome_type: "Reference proteome", 17 proteins) alongside two "Non Reference proteome" entries for the same organism (5 and 10 proteins) — always check proteome_type and prefer "Reference proteome" rather than assuming the first hit is canonical. Feeding UP000464024 into UniProtRef_get_proteome confirms components: [{"name": "Segment", "protein_count": 17, "genome_accession": "MN908947"}] (the real SARS-CoV-2 reference genome accession) and total_protein_count: 17. For human (UP000005640) and E. coli K-12 (UP000000625), get_proteome returns per-chromosome/plasmid component breakdowns the same way.

Registry duplication, verified live: UniProt_search_proteomes (in src/tooluniverse/data/uniprot_proteomes_tools.json, hitting rest.uniprot.org/proteomes/search directly) does the SAME search as UniProtRef_search_proteomes above, but is a separate, older tool implementation. Its advantage: one call returns the full rich record (BUSCO completeness, genome assembly, per-component protein counts, full citation list) that UniProtRef_search_proteomes requires a second UniProtRef_get_proteome call to obtain — verified live on organism_name: human, organism_name:escherichia coli, organism_name:mouse, all 3 returning the full nested object in one shot. If you only need the ID or proteomeType for triage, either tool works; if you need full detail immediately, prefer UniProt_search_proteomes and skip the follow-up call.

Sequence Archive and Clustering (UniParc, UniRef)

A different question again from Phases 1-3 and the proteome tools above: "has this exact sequence been seen before, and under how many accessions," and "what other sequences are near-identical to this one."

Real example (verified live, EGFR/human): UniParc_search {"query": "gene:EGFR AND organism_id:9606", "size": 3} -> 3 distinct UPI entries, each with a different set of UniProt accessions (Q8NDU8.1, Q9BZS2.1, Q9UMG5.1) and different oldest_created dates — UniParc treats each unique amino-acid string as one entry regardless of which UniProt accession(s) submitted it, so isoforms/fragments with distinct sequences get distinct UPIs even though they share a gene name. UniRef_get_cluster {"cluster_id": "UniRef90_P00533"} -> a real 119-member cluster spanning Boreoeutheria (the common ancestor taxon), with a representative_member (EGFR_HUMAN, 1210 aa) that carries 9+ merged UniProtKB accessions (P00533, O00688, ...) — note the seed_id (UPI0005F3CCCC, a UniParc ID) and representative_member are not always the same sequence.

Use UniParc when the question is "which UniProt accessions actually share this exact sequence" (deduplication); use UniRef when the question is "what else looks like this sequence at X% identity" (finding related proteins across species for MSA/phylogenetics input, or reducing redundancy before a proteome-wide analysis).

Subcellular Location Vocabulary (UniProt Locations)

UniProtLocations_search/UniProtLocations_get_location resolve UniProt's controlled subcellular-location vocabulary (organelles, membranes, topology, orientation) by ID (SL-XXXX) or free-text search.

Real gotcha, verified live: the common term "plasma membrane" does NOT surface UniProt's actual term for it — UniProt's controlled vocabulary calls this location "Cell membrane" (SL-0039), not "Plasma membrane." Searching "plasma membrane" or "Plasma membrane" returns only tangentially related hits (e.g. SL-0552 "Rhabdomere membrane," whose definition happens to mention "plasma membrane," not the term itself). Search a broader, UniProt-native term ("membrane", "cell") and scan the results rather than assuming your everyday biology term matches UniProt's naming — this is a real vocabulary mismatch, not a search bug.

Sample Metadata (EBI BioSamples)

BioSamples_search/BioSamples_search_by_filter/BioSamples_get_sample/ BioSamples_get_relationships/BioSamples_get_facets query EBI's 60M+ sample-metadata archive (organism, tissue, disease, experimental context) for samples that back sequencing/omics submissions — a different layer from the sequence itself, useful for "what samples exist for condition X" before going to ENA/SRA for the actual data.