### Ensembl Lookup (`ensembl-lookup`) Retrieves a single gene record, either directly by Ensembl gene ID or by gene symbol scoped to a species, returning the typed `EnsemblGene` (identifier, symbol, biotype, genomic coordinates, canonical transcript) plus the source URL and raw payload. With `expand` enabled, the response includes the nested transcript, translation, and exon hierarchy. #### API Reference

Source Ensembl gene ID (e.g. `ENSG...`). Gene symbol (e.g. `BRCA1`).

Source Species slug used when `symbol` is the input. Default `homo_sapiens`. Available options: `homo_sapiens`, `mus_musculus`, `rattus_norvegicus`, `danio_rerio`, `saccharomyces_cerevisiae` Genome assembly. `GRCh38` (default) calls `rest.ensembl.org`; `GRCh37` calls `grch37.rest.ensembl.org`. Available options: `GRCh38`, `GRCh37` Include transcripts, translations, and exons in the response. Default `False` matches Ensembl REST. Include MANE Select annotations (`/lookup/id` only; requires `expand=True`). Include phenotype annotations on gene records (`/lookup/id` only). Include UTR coordinates per transcript (`/lookup/id` only; requires `expand=True`). Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source The looked-up gene record. Ensembl gene ID (ENSG...). Human-readable gene symbol (e.g. 'BRCA1'). Free-text description. Gene biotype (protein\_coding, lncRNA, ...). Species slug (e.g. 'homo\_sapiens'). Chromosome / contig name. 1-indexed inclusive genomic start. 1-indexed inclusive genomic end. +1 or -1. Genome assembly name. Canonical transcript ID with version. Transcripts (PascalCase preserved from API); empty when `expand=False`. Final Ensembl REST URL that was hit. Raw API JSON.

#### Applications Use this to resolve a gene of interest as the entry point of nearly any Ensembl workflow. Convert a gene symbol such as `BRCA1` into its stable Ensembl gene ID, read off the canonical transcript and genomic coordinates for downstream transcriptomics, GWAS annotation, or sequence retrieval with [`ensembl-sequence`](https://bio-pro.mintlify.app/tools/database-retrieval/ensembl), or expand the transcript-and-exon hierarchy for splice-isoform analysis. The returned gene ID also feeds [`ensembl-overlap`](https://bio-pro.mintlify.app/tools/database-retrieval/ensembl) and [`ensembl-xrefs`](https://bio-pro.mintlify.app/tools/database-retrieval/ensembl). #### Usage Tips * **Provide exactly one of `ensembl_id` or `symbol`.** Supplying both or neither raises a validation error. A symbol lookup also requires `config.species` to disambiguate. * **Nested transcripts and exons are absent unless `expand` is set.** The default matches Ensembl REST and returns the gene record only, so request expansion explicitly when you need the transcript or exon hierarchy. * **`mane`, `phenotypes`, and `utr` apply only to ID-based lookup.** They are sent only on the `/lookup/id` path and are ignored for a symbol lookup. `mane` and `utr` additionally require `expand`.

### Ensembl Sequence (`ensembl-sequence`) Retrieves the sequence for an Ensembl gene, transcript, or protein ID and returns one or more `EnsemblSequence` records (stable ID, description, molecule type, sequence string) alongside the source URL and raw payload. #### API Reference

Source Ensembl ID (`ENSG...`, `ENST...`, or `ENSP...`).

Source What to return — `genomic` (DNA + UTRs + introns), `cdna` (spliced mRNA + UTRs), `cds` (spliced coding only), `protein` (translation). Available options: `genomic`, `cdna`, `cds`, `protein` Genome assembly. `GRCh38` (default) or `GRCh37`. Available options: `GRCh38`, `GRCh37` Return all sequences when an ID maps to multiple records (e.g. patches, alternative haplotypes). Mask repeats in the returned sequence. `hard` replaces with `N`; `soft` lowercases. Genomic sequence\_type only; mutually exclusive with mask\_feature. Mask introns (when `sequence_type='genomic'`) or UTRs (when `sequence_type='cdna'`) so the primary feature stands out. Mutually exclusive with `mask`. Bases to add to the 3' end (genomic only, incompatible with `end`). Bases to add to the 5' end (genomic only, incompatible with `start`). 1-indexed start trim coordinate (incompatible with `expand_5prime`). 1-indexed end trim coordinate (incompatible with `expand_3prime`). Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source Fetched sequence record(s). Length 1 unless `multiple_sequences=True` and the ID maps to more than one. Stable ID echoed by the server. May differ from the input ID — for example, an ENST input with `type=protein` resolves to the corresponding ENSP. Description string returned by the server. Molecule type ('dna' / 'protein' / ...). The raw sequence string. Molecule type ('dna', 'protein', ...) Final Ensembl REST URL that was hit. Raw API JSON, always wrapped in a list.

#### Applications Use this to retrieve a reference sequence at gene, transcript, or protein granularity for any downstream analysis. Fetch the spliced mRNA or coding sequence of a canonical transcript resolved by [`ensembl-lookup`](https://bio-pro.mintlify.app/tools/database-retrieval/ensembl) for primer design, codon-usage analysis, or sequence comparison, pull the genomic span with introns for promoter or splice-site studies, or obtain the protein translation for multiple-sequence alignment or structure prediction. Repeat masking and feature masking support cis-element and intron-aware analyses. #### Usage Tips * **The returned `id` may differ from the input ID.** Requesting a protein sequence for a transcript ID resolves to the corresponding protein ID, so read the record's `id` rather than assuming it echoes the input. * **`mask` and `mask_feature` are mutually exclusive, as are the expand and trim pairs.** Setting both masks, or both `expand_5prime` and `start`, or both `expand_3prime` and `end`, raises a validation error. * **Repeat masking and span expansion apply to genomic sequence only.** They have no effect on `cdna`, `cds`, or `protein` requests. * **Set `multiple_sequences` when an ID maps to more than one record.** Without it, IDs that resolve to multiple sequences (patches, alternative haplotypes) return only the first.

### Ensembl Overlap (`ensembl-overlap`) Retrieves features overlapping the genomic region of a given Ensembl ID and returns a list of `EnsemblOverlapFeatureRecord` entries, each exposing the common typed fields (feature type, identifier, biotype, coordinates, strand, region) plus a `raw` dict carrying the full upstream record. #### API Reference

Source Ensembl ID whose region to query for overlapping features.

Source Type of feature to retrieve (e.g. gene, transcript, exon, regulatory, variation). Available options: `band`, `gene`, `transcript`, `cds`, `exon`, `repeat`, `simple`, `misc`, `variation`, `somatic_variation`, `structural_variation`, `somatic_structural_variation`, `constrained`, `regulatory`, `motif`, `mane` Genome assembly. `GRCh38` (default) or `GRCh37`. Available options: `GRCh38`, `GRCh37` Restrict to a biotype (e.g. `protein_coding`); most useful when `overlap_feature` is `gene` or `transcript`. Restrict variation features by Sequence Ontology consequence (e.g. `missense_variant`). Restrict variation features to a named variant set (e.g. `ClinVar`). Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source Features overlapping the queried region; each carries the full upstream dict in `raw` for feature-specific keys. Feature type ('gene', 'transcript', 'exon', 'regulatory', 'motif', 'variation', ...). Feature ID where the API returns one. Biotype where applicable. 1-indexed inclusive genomic start. 1-indexed inclusive genomic end. +1, -1, or 0 for unstranded features. Chromosome / contig name. Full upstream record for feature-specific fields. Final Ensembl REST URL that was hit. Raw API JSON.

#### Applications Use this to annotate a genomic locus by listing what overlaps it. Identify which gene or transcript contains a GWAS hit, ChIP-seq peak, or ATAC-seq peak, enumerate the regulatory-build features (promoters, enhancers, transcription-factor binding sites) within a region for functional-genomics analysis, or pull overlapping variants filtered to a named set such as ClinVar to ask whether the region is clinically annotated. The locus is typically obtained from [`ensembl-lookup`](https://bio-pro.mintlify.app/tools/database-retrieval/ensembl). #### Usage Tips * **Records are typed only on the common fields. Feature-specific keys live in `raw`.** Different feature classes return divergent payload shapes, so read per-feature attributes from each record's `raw` dict. * **`biotype` is most meaningful for gene and transcript features.** It filters those classes. Pairing it with unrelated feature types is unlikely to narrow results. * **`so_term` and `variant_set` apply to variation features.** They have no effect when the feature class is not a variation type.

### Ensembl Xrefs (`ensembl-xrefs`) Resolves an Ensembl ID to its external-database cross-references and returns a list of `EnsemblXref` records (external database name, display and primary identifiers, description, cross-reference type) plus the source URL and raw payload. #### API Reference

Source Ensembl ID for direct cross-reference lookup.

Source Genome assembly. `GRCh38` (default) or `GRCh37`. Available options: `GRCh38`, `GRCh37` Fan out to transcripts and translations. On a gene query this also returns xrefs from each child transcript and protein. Restrict to one external database (e.g. `UniProtKB/Swiss-Prot`, `HGNC`). Restrict to one feature type when the stable ID resolves ambiguously. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source Cross-reference records to external databases (UniProt, EntrezGene, RefSeq, ...). External database name (e.g. 'Uniprot\_gn', 'EntrezGene'). Human-readable DB name. Display identifier in the external DB. Primary identifier in the external DB. External-DB description. Cross-reference type ('DIRECT', 'DEPENDENT', ...). Final Ensembl REST URL that was hit. Raw API JSON.

#### Applications Use this to convert identifiers between Ensembl and the other major sequence, gene, and protein resources. Map an Ensembl gene or protein to a UniProt accession before fetching its entry with [`uniprot-fetch`](https://bio-pro.mintlify.app/tools/database-retrieval/uniprot), which then bridges through to PDB structures via SIFTS, recover EntrezGene or RefSeq identifiers for NCBI-side retrieval, or follow GO and InterPro cross-references for functional annotation. The Ensembl ID is commonly produced by [`ensembl-lookup`](https://bio-pro.mintlify.app/tools/database-retrieval/ensembl). #### Usage Tips * **Filter on `dbname` in the result, not just `external_db`.** A single query can return several UniProt-related and RefSeq-related entries, so select the row by its `dbname` rather than assuming one record per database. * **`all_levels` changes result scope on gene queries.** It fans cross-references out to child transcripts and translations, which can substantially enlarge the result. * **Set `object_type` when a stable ID resolves ambiguously.** It restricts results to one feature type when the ID could map to a gene, transcript, or translation.

### Ensembl VEP (`ensembl-vep`) Submits an HGVS notation to the Ensembl Variant Effect Predictor REST endpoint and returns a list of `EnsemblVEPConsequence` records (echoed input, most severe consequence as a Sequence Ontology term, region and coordinates, allele string, raw per-transcript consequences, co-located variants) plus a derived `num_consequences` count. #### API Reference

Source HGVS notation. Genomic (e.g. `9:g.22125504G>C`), coding (`ENST00000357654:c.5074G>A`), or protein (`ENSP00000418960:p.Tyr124Cys`) forms all work.

Source Species slug. Default `homo_sapiens`. Available options: `homo_sapiens`, `mus_musculus`, `rattus_norvegicus`, `danio_rerio`, `saccharomyces_cerevisiae` Genome assembly. `GRCh38` (default) or `GRCh37`. Available options: `GRCh38`, `GRCh37` Collapsible group of species-agnostic annotation toggles. Mark canonical Ensembl transcripts in each consequence record. Include HGVS notation per consequence. Include Ensembl protein identifiers. List overlapping protein domain names. Include affected exon/intron numbers. Include Sequence Ontology variant class. Include UniProt accession for each transcript. Include RefSeq cross-reference IDs. Include overlapping miRNA target sites. Include PubMed citation IDs. Include conservation scores from EPO alignments. Include overlapping phenotype/disease annotations. Include BLOSUM62 substitution score for missense. Include MaxEntScan splice-site scores. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded. SIFT pathogenicity output — `b` (both prediction + score), `p` (prediction only), `s` (score only); `None` falls back to API default. PolyPhen output level; same value semantics as `sift`. Include MANE Select annotations (GRCh38 only). AlphaMissense missense pathogenicity scores (human only). REVEL ensemble pathogenicity scores (human only). CADD deleteriousness scores (human only). Include APPRIS principal isoform tag (human/mouse only). Include transcript support level (human/mouse only). Include CCDS identifier per transcript (human/mouse only). Up/downstream distance (bp) used to assign consequence terms. `None` keeps the API default (5000). Return only one consequence per variant — Ensembl's PICK heuristic (canonical, longest CDS, …). Return one consequence per gene (less aggressive than `pick`); incompatible with `pick`. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source One record per VEP input (Ensembl returns a list even for a single HGVS). HGVS string the API echoed back. Highest-severity consequence term (Sequence Ontology: `intron_variant`, `missense_variant`, `stop_gained`, …). Chromosome / contig. 1-indexed inclusive genomic start. 1-indexed inclusive genomic end. +1 or -1. Reference/alternate alleles (e.g. 'G/C'). Per-transcript consequence records — kept as raw dicts because the field set (sift\_prediction, polyphen\_prediction, codons, amino\_acids, …) varies by consequence type and plugin configuration. Co-located known variants (rsIDs, frequencies, clinical significance) — also kept raw. Final URL hit. Raw API JSON.

#### Applications Use this to predict the functional consequence of a variant and assess its likely impact. Classify a coding or genomic HGVS notation as missense, synonymous, stop-gain, splice-disrupting, or noncoding, then read per-transcript SIFT and PolyPhen predictions alongside optional human-only AlphaMissense, REVEL, and CADD pathogenicity scores for clinical or research variant interpretation. Co-located variant lookups surface population-frequency context from gnomAD and ClinVar annotations. Candidate variants are often identified from features returned by [`ensembl-overlap`](https://bio-pro.mintlify.app/tools/database-retrieval/ensembl) or from a designed or observed substitution in a downstream design workflow. #### Usage Tips * **`transcript_consequences` and `colocated_variants` are returned as raw dicts.** Their field sets vary by consequence type and annotation toggles, so read them defensively rather than expecting a fixed shape. * **`pick` and `per_gene` cannot be combined.** Setting both raises a validation error. Choose one collapse strategy. * **Several annotations are species- or assembly-restricted.** MANE applies to GRCh38 only. AlphaMissense, REVEL, and CADD are human only. APPRIS, TSL, and CCDS are human and mouse only. Enabling a restricted annotation outside its scope simply yields no extra data. * **A coding or genomic HGVS form is more reliable than a protein form.** A protein-level notation can map to multiple transcripts ambiguously, so prefer coding or genomic notation when available.