Lifesciences Genomics

Genomics API Skills

Query genomic databases via MCP tools (primary) or curl (fallback).

Grounding Rule

All gene names, IDs, and annotations MUST come from API results. Do NOT provide gene information from training knowledge. If a query returns no results, report "No results found."

MCP Token Budgeting (slim Parameter)

All MCP tools in this skill support a slim parameter for token-efficient queries:

When to use slim=true:

• LOCATE phase: Fast candidate lists (returns ~20 tokens/entity vs ~115-300 tokens)
• Batch operations: Resolving multiple entities in a single turn
• Exploration: Quick overviews without full metadata

When to use slim=false (default):

• RETRIEVE phase: Need full metadata with cross-references
• Validation: Verifying detailed properties
• Graph persistence: Collecting complete entity records

Example:

# LOCATE: Find top 10 gene candidates (slim=true for speed)
Call `hgnc_search_genes` with: {"query": "TNF", "slim": true, "page_size": 10}
→ Returns minimal fields: ID, symbol, name only (~20 tokens each)

# RETRIEVE: Get full record for validation (slim=false, default)
Call `hgnc_get_gene` with: {"hgnc_id": "HGNC:11892"}
→ Returns complete metadata with cross-references (~115 tokens)

Impact: Using slim=true during LOCATE enables 5-10x more entities per LLM turn without context overflow.

Reference: This token budgeting pattern is detailed in reference/prior-art-api-patterns.md (Section 7.1).

LOCATE → RETRIEVE Patterns

Gene Resolution (HGNC — Start Here)

LOCATE: Search for gene by symbol or name

PRIMARY (MCP tool):

Call `hgnc_search_genes` with: {"query": "TP53"}
→ Returns candidates with HGNC IDs, symbols, names

FALLBACK (curl):

curl -s "https://rest.genenames.org/search/symbol/TP53" \
  -H "Accept: application/json" | jq '.response.docs[0] | {hgnc_id, symbol, name}'

RETRIEVE: Fetch full record by HGNC ID

PRIMARY (MCP tool):

Call `hgnc_get_gene` with: {"hgnc_id": "HGNC:11998"}
→ Returns: symbol, name, cross-references (UniProt, Ensembl, Entrez)

FALLBACK (curl):

curl -s "https://rest.genenames.org/fetch/hgnc_id/11998" \
  -H "Accept: application/json" | jq '.response.docs[0]'

Gene Metadata (Ensembl)

LOCATE: Resolve symbol to Ensembl ID

PRIMARY (MCP tool):

Call `ensembl_search_genes` with: {"query": "TP53", "species": "homo_sapiens"}
→ Returns Ensembl gene ID (ENSG...)

FALLBACK (curl):

curl -s "https://rest.ensembl.org/lookup/symbol/homo_sapiens/TP53?content-type=application/json" \
  | jq '{id, display_name}'

RETRIEVE: Get full gene metadata by Ensembl ID

PRIMARY (MCP tool):

Call `ensembl_get_gene` with: {"ensembl_id": "ENSG00000141510"}
→ Returns: biotype, description, location, transcripts

FALLBACK (curl):

curl -s "https://rest.ensembl.org/lookup/id/ENSG00000141510?expand=1&content-type=application/json" \
  | jq '{id, display_name, biotype, description, seq_region_name, start, end}'

Variant Annotation (Ensembl VEP)

No MCP tool — use curl directly:

LOCATE: Annotate variant by rsID

curl -s "https://rest.ensembl.org/vep/human/id/rs56116432?content-type=application/json" \
  | jq '.[0] | {most_severe_consequence, transcript_consequences: .transcript_consequences[:2]}'

RETRIEVE: Annotate by HGVS notation (batch via POST)

curl -s -X POST "https://rest.ensembl.org/vep/human/hgvs" \
  -H "Content-Type: application/json" \
  -d '{"hgvs_notations": ["ENST00000366667:c.803C>T"]}' \
  | jq '.[0].transcript_consequences[0] | {consequence_terms, sift_prediction, polyphen_prediction}'

Orthology (Ensembl)

No MCP tool — use curl directly:

LOCATE + RETRIEVE (single call returns both):

curl -s "https://rest.ensembl.org/homology/id/human/ENSG00000141510?type=orthologues&content-type=application/json" \
  | jq '.data[0].homologies[:5][] | {species: .target.species, gene_id: .target.id, perc_id: .target.perc_id}'

Cross-Database ID Resolution (Ensembl xrefs)

No MCP tool — use curl directly:

RETRIEVE: Get all cross-references for a gene (useful for verification)

curl -s "https://rest.ensembl.org/xrefs/id/ENSG00000141510?content-type=application/json" \
  | jq '.[] | select(.dbname | test("HGNC|UniProt|OMIM|RefSeq")) | {db: .dbname, id: .primary_id}'

Linkage Disequilibrium (Ensembl)

No MCP tool — use curl directly:

RETRIEVE: LD between two variants

curl -s "https://rest.ensembl.org/ld/human/pairwise/rs56116432/rs1042522?population_name=1000GENOMES:phase_3:EUR&content-type=application/json" \
  | jq '.[0] | {r2, d_prime}'

RETRIEVE: LD in genomic region

curl -s "https://rest.ensembl.org/ld/human/region/17:7668421..7687490/1000GENOMES:phase_3:EUR?content-type=application/json" \
  | jq '.[:3]'

NCBI E-utilities: Gene Search & Links

LOCATE: Search for gene

PRIMARY (MCP tool):

Call `entrez_search_genes` with: {"query": "TP53", "organism": "human"}
→ Returns Entrez gene IDs

FALLBACK (curl):

curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gene&term=TP53[sym]+AND+human[orgn]&retmode=json" \
  | jq '.esearchresult | {count, idlist}'

RETRIEVE: Get gene summary by Entrez ID

PRIMARY (MCP tool):

Call `entrez_get_gene` with: {"gene_id": "7157"}
→ Returns gene name, description, chromosome location

FALLBACK (curl):

curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=gene&id=7157&retmode=json" \
  | jq '.result["7157"] | {name: .name, description: .description, chromosome: .chromosome}'

RETRIEVE: Link gene to PubMed articles

PRIMARY (MCP tool):

Call `entrez_get_pubmed_links` with: {"gene_id": "7157"}
→ Returns linked PubMed article IDs

FALLBACK (curl):

curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=gene&db=pubmed&id=7157&retmode=json" \
  | jq '.linksets[0].linksetdbs[] | select(.dbto=="pubmed") | {db: .dbto, count: (.links | length)}'

Quick Reference

ID Format Reference

Rate Limits

Query Best Practices

Human-Centric Defaults

• Filter to human by default unless performing comparative genomics
• Use human[orgn] in NCBI searches, homo_sapiens for Ensembl
• Only omit organism filter when explicitly comparing across species (e.g., ortholog analysis)

Efficient Querying

• Use page_size=10 for exploration
• Use cross-reference endpoints to resolve IDs rather than multiple searches
• Prefer Ensembl IDs (ENSG*) for programmatic access — most APIs accept them

See Also

• lifesciences-graph-builder: Orchestrator for full Fuzzy-to-Fact protocol
• lifesciences-proteomics: UniProt, STRING, BioGRID protein endpoints