ncbi-gene-search

Purpose

Resolve a gene symbol through NCBI E-utilities and return concise Gene database summaries.

When to use

• You need an official Entrez Gene identifier for a symbol and species.
• You want a quick NCBI summary before a larger genomics workflow.

When not to use

• You need transcript-level coordinates or large-batch annotation.
• You need clinical interpretation or variant effect prediction.
• You need offline execution.

Inputs

• Gene symbol
• Optional species, maximum result count, email, and output path

Outputs

• JSON payload containing the query, matched Gene IDs, and compact gene summaries

Requirements

• Python 3.10+
• Network access to eutils.ncbi.nlm.nih.gov

Procedure

1. Run python3 skills/genomics/ncbi-gene-search/scripts/search_ncbi_gene.py --symbol BRCA1 --species "homo sapiens" --retmax 1 --out skills/genomics/ncbi-gene-search/assets/brca1_gene_summary.json.
2. Inspect the genes list for gene_id, symbol, description, organism, and map_location.
3. Use the NCBI gene ID in downstream lookup or literature workflows when needed.

Validation

• Command exits successfully.
• search.ids contains at least one Gene ID for a known symbol.
• The first result has a non-empty symbol and organism.

Failure modes and fixes

• No hits: confirm the symbol and organism spelling.
• Unexpected species: make the organism explicit with --species.
• Too many matches: lower --retmax and review the returned summaries.

Safety and limits

• Metadata lookup only.
• This skill does not perform variant interpretation or clinical classification.

Example

• python3 skills/genomics/ncbi-gene-search/scripts/search_ncbi_gene.py --symbol TP53 --species "homo sapiens" --retmax 1

Provenance

• NCBI E-utilities: https://www.ncbi.nlm.nih.gov/books/NBK25501/
• NCBI Developer APIs: https://www.ncbi.nlm.nih.gov/home/develop/api/

Related skills

• ensembl-gene-lookup
• ncbi-pubmed-search