tooluniverse-sequence-retrieval - Claude MCP Skill

# 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

| Prefix | Type | Use With |
|--------|------|----------|
| NC_/NM_/NR_/NP_/XM_ | RefSeq | NCBI only |
| U*/M*/K*/X*/CP*/NZ_ | GenBank | NCBI or ENA |
| EMBL format | EMBL | ENA preferred |

**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.

```python
# 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

| Primary | Fallback | Notes |
|---------|----------|-------|
| NCBI_get_sequence | ENA (if GenBank format) | NCBI unavailable |
| ena_get_entry | NCBI_get_sequence | ENA doesn't have RefSeq |
| NCBI_search_nucleotide | Try broader keywords | No results |
| NCBI_get_sequence / ena_get_sequence_fasta | dbfetch_fetch_entry (db="refseqn"/"ena_sequence") | Both NCBI and ENA-specific tools unavailable; dbfetch mirrors the same underlying records |

---

## 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

| Tier | Prefix | Description |
|------|--------|-------------|
| RefSeq Reference (best) | NC_, NM_, NP_ | NCBI-curated, gold standard |
| RefSeq Predicted | XM_, XP_, XR_ | Computationally predicted |
| GenBank Validated | Various | Submitted, some curation |
| GenBank Direct | Various | Direct submission |
| Third Party | TPA_ | Third-party annotation |

---

## 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

| Error | Response |
|-------|----------|
| "No search criteria provided" | Add organism, gene, or keywords |
| "ENA 404 error" | Likely RefSeq -- use NCBI only |
| "No results found" | Broaden search, check spelling, try synonyms |
| "Sequence too large" | Note size, provide download link instead |

---

## 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.

| Tool | Resolves | Key output |
|---|---|---|
| `UniProtRef_search_proteomes` | organism name/taxon ID -> matching proteome ID(s) | `id` (`UPXXXXXXXXX`), `organism`, `taxon_id`, `proteome_type` (Reference/Non Reference), `protein_count` |
| `UniProtRef_get_proteome` | one proteome ID -> full organism/assembly detail | `organism.scientific_name`/`taxon_id`, `components[]` (`name`, `protein_count`, `genome_accession`), `total_protein_count` |

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."

| Tool | Answers | Key params |
|---|---|---|
| `UniParc_search` | Find all UPI archive entries for a gene/organism/keyword | `query` (UniProt query syntax, e.g. `"gene:EGFR AND organism_id:9606"`), `size` |
| `UniParc_get_entry` | Full sequence + every UniProt accession that ever pointed to this exact sequence, across every database load | `upi` |
| `UniRef_search_clusters` | Find sequence-similarity clusters for a gene/organism/keyword | `query`, `cluster_type` (UniRef100/90/50), `size` |
| `UniRef_get_cluster` | Cluster detail: member count, representative sequence, common taxon | `cluster_id` (e.g. `UniRef90_P00533`) |

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.

**Real gotcha, verified live:** `BioSamples_search` with a multi-word
phrase (`"EGFR lung adenocarcinoma"`) returned **zero** results, while the
single term `"EGFR"` returned real hits immediately — the search does not
implicitly AND multiple free-text words the way a search engine would.
Use one keyword at a time, or use `BioSamples_search_by_filter` (structured
`attribute`/`value` pairs, e.g. `attribute="organism", value="Homo
sapiens"`) when you need to combine multiple real constraints. `get_facets`
is useful up front to discover which attribute values actually exist
before filtering on one (verified live: returns real facet counts, e.g.
432,302 samples for a broad text query).

## Organism Taxonomy (EBI Taxonomy)

`EBITaxonomy_get_by_id`/`get_by_scientific_name`/`search_by_name`/`suggest`
resolve organism names/IDs (NCBI Taxonomy, mirrored by EBI) — lineage,
rank, division, genetic code. Use `search_by_name` for common names
("mouse," "fruit fly") and `suggest` for type-ahead partial matching;
`get_by_scientific_name`/`get_by_id` for an exact, already-known name/ID.
Verified live: `Homo sapiens` -> `tax_id: "9606"`, full lineage string
`"Eukaryota; Metazoa; Chordata; ... Hominidae; Homo;"`.

## Cross-Domain Quick Lookup (BioThings Gateway)

`BioThings_list_apis`/`BioThings_query`/`BioThings_get_entity`/
`BioThings_get_metadata` reach ~50 BioThings-hosted APIs (drug-drug
interactions, gene-disease text-mining, PubMed-mined predications, and
more) through one Elasticsearch-style query interface — useful as a fast
first check for whether ToolUniverse has DEDICATED coverage of a resource
before reaching for this generic gateway (`BioThings_list_apis`'s
`preferred_tooluniverse_tool` field tells you when a richer dedicated tool
already exists; prefer that instead). Call `BioThings_get_metadata` before
writing a fielded `BioThings_query` so field names are correct. Verified
live: `BioThings_get_entity {"api": "mondo", "entity_id": "MONDO:0010329"}`
returns a real MONDO disease-ontology record with ancestor terms; querying
the `ddinter` API returns real drug-drug-interaction pairs with severity.
This complements `tooluniverse-data-integration-analysis`'s multi-database
evidence-gathering workflow as a fast single-call option when a dedicated
tool doesn't already exist for the resource you need.

## Cross-Database ID Resolution (Bioregistry, Identifiers.org, TogoID)

Three overlapping registries for "I have an ID in system A, what's the equivalent in system B" — verified live with a shared example (human TP53): NCBI Gene `7157` -> `TogoID_convert {"ids": "7157", "source": "ncbigene", "target": "ensembl_gene"}` -> real `ENSG00000141510`; that Ensembl gene's HGNC ID `11998` resolves via both `Bioregistry_resolve_reference {"prefix": "hgnc", "identifier": "11998"}` and `IdentifiersOrg_resolve {"namespace": "hgnc", "local_id": "11998"}` to the same genenames.org record, confirming the two registries agree.

- **Bioregistry** (`Bioregistry_resolve_reference`/`get_registry`/`get_prefix_mappings`/`search_registries`) — 2600+ prefixes, returns multiple provider URLs per identifier (bioregistry.io, identifiers.org, n2t.net, bio2rdf, and resource-specific links like GenCC/INDRA when relevant) plus prefix metadata (ID regex pattern, homepage). Use `search_registries` first when you don't know the exact prefix for a database.
- **Identifiers.org** (`IdentifiersOrg_resolve`/`get_namespace`/`search_namespaces`/`list_namespaces`) — the original MIRIAM registry; `resolve` returns full institutional/provider metadata (which organization hosts the resolver, recommended vs. alternate providers) that Bioregistry's `default` link doesn't surface. Prefer this when you need to know WHO operates the canonical resolver for a namespace, not just a URL.
- **TogoID** (`TogoID_convert`/`list_datasets`) — the only one of the three that actually CONVERTS an ID between 117 dataset types (not just gives you a URL for the ID you already have) — e.g. NCBI Gene -> Ensembl Gene -> UniProt -> PDB in one call each. Call `list_datasets` first to get valid `source`/`target` dataset-type strings.

Reach for this cluster when a workflow needs to hop between ID systems that this skill's dedicated tools (UniProt/UniParc/UniRef/EBI Taxonomy above) don't directly connect — e.g. converting a variant-analysis skill's Ensembl gene ID into the NCBI Gene ID a different tool expects.

## EBI dbfetch (One Interface, Many Databases)

`dbfetch_fetch_entry` (`db`, `id`, `format`) / `dbfetch_fetch_batch` (`db`, `ids` comma-separated, `format`) / `dbfetch_list_databases` / `dbfetch_list_formats` — fetches raw records by accession from any of 16 EBI-hosted databases (`uniprotkb`, `pdb`, `embl`, `ena_sequence`, `refseqp`, `refseqn`, `ensemblgene`, `ensembltranscript`, `interpro`, `medline`, `taxonomy`, `uniprot`, `chembl`, `afdb`, `imgtligm`, `hgnc`) through one uniform call, and can fetch several accessions from the same database in a single request via `fetch_batch`. No API key required. Verified live: `dbfetch_fetch_entry {"db": "uniprotkb", "id": "P04637", "format": "fasta"}` returns the real human p53 (P53_HUMAN) FASTA sequence; `dbfetch_fetch_batch {"db": "uniprotkb", "ids": "P04637,P01308", "format": "fasta"}` returns both p53 and insulin in one response.

**When to use this instead of the dedicated tools above**: reach for dbfetch when you need one-off or batch fetches across DIFFERENT database types without juggling per-database tools/clients (e.g. grabbing a UniProt entry and a PDB entry and an EMBL entry in a short session), or specifically need `fetch_batch`'s multi-accession-in-one-call convenience. Prefer the dedicated tools above (UniProt/UniParc/ENA/NCBI) when you need their richer structured fields (cross-references, feature annotations, curation-level metadata) — dbfetch returns the database's native flat/FASTA/XML text, not a parsed structured object.