Database Lookup

You have access to 78 public databases through their REST APIs. Your job is to figure out which database(s) are relevant to the user's question, query them, and return the raw JSON results along with which databases you used.

Core Workflow

1. Understand the query — What is the user looking for? A compound? A gene? A pathway? A patent? Expression data? An economic indicator? This determines which database(s) to hit.

2. Select database(s) — Use the database selection guide below. When in doubt, search multiple databases — it's better to cast a wide net than to miss relevant data.

3. Read the reference file — Each database has a reference file in

   references/

   with endpoint details, query formats, and example calls. Read the relevant file(s) before making API calls.

4. Make the API call(s) — See the Making API Calls section below for which HTTP fetch tool to use on your platform.

5. Return results — Always return:

   • The raw JSON response from each database
   • A list of databases queried with the specific endpoints used
   • If a query returned no results, say so explicitly rather than omitting it

Database Selection Guide

Match the user's intent to the right database(s). Many queries benefit from hitting multiple databases.

Physics & Astronomy

Earth & Environmental Sciences

Chemistry & Drugs

Materials Science & Crystallography

Biology & Genomics

Organism/species matters. Most biology databases cover multiple organisms. If the user's query is about a specific organism, pass it explicitly — don't assume human. Common patterns: Ensembl uses

{species}

homo_sapiens

species=9606

10090

organism_id:9606

hsa

mmu

Disease & Clinical

Patents & Regulatory

Economics & Finance

Social Sciences & Demographics

Cross-domain queries

When the user's query spans multiple domains (e.g. "what do we know about aspirin" or "find everything about BRCA1"), query all relevant databases in parallel.

Common Identifier Formats

Different databases use different identifier systems. If a query fails, the identifier format may be wrong. Here's a quick reference:

P#####

Q#####

P04637

ENSG###########

ENSG00000141510

7157

HGNC:#####

HGNC:11998

2244

ZINC

ZINC000000000053

PRJEB

PRJEB40665

ERR

ERR1234567

ERX

ERX1234567

ERS

ERS1234567

CHEMBL####

CHEMBL25

R-HSA-######

R-HSA-109581

HP:#######

HP:0001250

MONDO:#######

MONDO:0007947

GO:#######

GO:0008150

rs########

rs334

ENSG###.##

ENSG00000139618.17

Identifier Resolution

When a database doesn't recognize an identifier, convert it using these workflows:

Genes: Symbol (e.g. "TP53") → look up in NCBI Gene (esearch by symbol) → get NCBI Gene ID → convert to Ensembl ID via Ensembl

/xrefs/symbol/homo_sapiens/{symbol}

gene_exact:{symbol} AND organism_id:9606

Compounds: Name → PubChem

/compound/name/{name}/cids/JSON

Variants: rsID (e.g. "rs334") works directly in dbSNP, ClinVar, GWAS Catalog, gnomAD. For genomic coordinates, use Ensembl VEP to get consequence annotations and linked rsIDs.

Diseases: Name → Open Targets or Monarch search → get EFO or MONDO ID → use in downstream queries.

POST-Only APIs

These databases require HTTP POST and will not work with WebFetch (GET-only). Use

curl

curl -X POST -H "Content-Type: application/json" -d '{"query":"..."}' https://api.platform.opentargets.org/api/v4/graphql

curl -X POST -H "Content-Type: application/json" -d '{"query":"..."}' https://gnomad.broadinstitute.org/api

curl -X POST -H "Content-Type: application/json" -d '{"genes":["..."]}' https://rummageo.com/api/enrich

curl -X POST -H "Content-Type: application/json" -d '{"filters":...}' https://api.gdc.cancer.gov/ssms

curl -H "User-Agent: YourApp you@email.com" https://efts.sec.gov/LATEST/search-index?q=...

API Keys and Access Restrictions

Some databases require API keys or have access restrictions. When an API key is needed:

1. Check the current environment first — the key may already be exported as a shell environment variable (e.g.

   $FRED_API_KEY

   ). Read it directly from the environment.
2. Fall back to

   .env

   — if the variable isn't in the environment, check the

   .env

   file in the current working directory.
3. If neither has it — proceed without the key (most APIs still work at lower rate limits) and tell the user which key is missing and how to get one.

Databases requiring API keys (free registration)

FRED_API_KEY

BEA_API_KEY

BLS_API_KEY

NCBI_API_KEY

OPENFDA_API_KEY

PATENTSVIEW_API_KEY

DATACOMMONS_API_KEY

MP_API_KEY

NASA_API_KEY

NOAA_API_KEY

OPENWEATHERMAP_API_KEY

OMIM_API_KEY

BIOGRID_API_KEY

ALPHAVANTAGE_API_KEY

CENSUS_API_KEY

DISGENET_API_KEY

ADDGENE_API_KEY

CLUE_API_KEY

These are all free to obtain. The APIs work without keys but have lower rate limits. Always try with a key first — if the env variable isn't set, proceed without the key and note in your response that rate limits may be lower.

Databases with paid or restricted access

When a database requires paid access or registration the user hasn't set up:

1. Fall back to a free alternative that can answer the same question
2. Tell the user which database you couldn't access, why, and what you used instead
3. If the user specifically requests a restricted database, explain the access requirements so they can set it up

Loading API keys

Step 1 — Check the current environment. The key may already be exported as a shell variable. For example, in Claude Code you can check with Bash:

echo $FRED_API_KEY

Step 2 — Check

.env

.env

FRED_API_KEY=your_key_here
BEA_API_KEY=your_key_here

Step 3 — Proceed without. If neither source has the key, proceed without it (most APIs still work at lower rate limits) and mention this to the user.

Making API Calls

Use your environment's HTTP fetch tool to call REST endpoints. The tool name varies by platform:

WebFetch

curl

web_fetch

curl

read_url_content

curl

curl

run_terminal_cmd

curl

shell

curl

execute_command

If you don't recognize your platform or the fetch tool fails, fall back to

curl

curl -s -H "Accept: application/json" "https://api.example.com/endpoint"

Request guidelines

• Set

  Accept: application/json

  header where supported
• URL-encode special characters in query parameters — SMILES strings (

  /

  ,

  #

  ,

  =

  ,

  @

  ), compound names with parentheses, and ontology terms with colons (

  HP:0001250

  →

  HP%3A0001250

  ) are common sources of failures. With

  curl

  , use

  --data-urlencode

  for safety.
• Parallel OK: When querying different databases (e.g., PubChem + ChEMBL + Reactome), run them in parallel — most APIs have generous rate limits.
• Serialize requests to rate-limited APIs: NCBI APIs (Gene, GEO, Protein, Taxonomy, dbSNP, SRA) at 3 req/sec without key, 10 with key. Also watch: Ensembl (15 req/sec), BLS v1 (25 req/day without key), SEC EDGAR (10 req/sec), NOAA (5 req/sec with token).
• If you get a rate-limit error (HTTP 429 or 503), wait briefly and retry once

Error recovery

If an API returns an error or empty results:

1. Check the identifier format — use the Common Identifier Formats table above. A gene symbol may need to be converted to NCBI Gene ID or Ensembl ID first.
2. Try alternative identifiers — if a compound name fails in PubChem, try SMILES, InChIKey, or CID. If a gene symbol fails, try the NCBI Gene ID.
3. Try a different database — if one database is down or returns nothing, check the "Also consider" column in the selection guide for alternatives.
4. Report the failure — tell the user which database failed, the error, and what you tried instead.

Pagination

Many APIs return paginated results — if you only read the first page, you may miss data. Common patterns:

• Offset/Limit:

  offset=0&limit=100

  → increment offset by limit for the next page (ChEMBL, FRED, NOAA, USGS, NCBI E-utilities, ENA, GDC, FDA)
• Cursor-based: Response includes a

  nextPageToken

  or

  cursor

  value — pass it in the next request (ClinicalTrials.gov, UniProt)
• Page number:

  page=1&per_page=50

  → increment page (World Bank, cBioPortal, ZINC)

Check the reference file for each database's specific pagination parameters. If a response includes

total

totalCount

next

For targeted lookups (single gene, single compound), the first page is usually sufficient. Paginate when the user needs comprehensive results (e.g., "all clinical trials for X" or "all known variants in gene Y").

Output Format

Structure your response like this:

## Databases Queried
- **PubChem** — /compound/name/aspirin/property/...
- **Reactome** — /search/query?query=aspirin

## Results

### PubChem
[raw JSON response]

### Reactome
[raw JSON response]

If results are very large, present the most relevant portion and note that additional data is available. But default to showing the full raw JSON — the user asked for it.

Adding New Databases

This skill is designed to grow. Each database is a self-contained reference file in

references/

1. Create

   references/<database-name>.md

   following the same format as existing files
2. Add an entry to the database selection guide above
3. The reference file should include: base URL, key endpoints, query parameter formats, example calls, rate limits, and response structure

Available Databases

Read the relevant reference file before making any API call.

Physics & Astronomy

references/nasa.md

references/nasa-exoplanet-archive.md

references/nist.md

references/sdss.md

references/simbad.md

Earth & Environmental Sciences

references/usgs.md

references/noaa.md

references/epa.md

references/openweathermap.md

Chemistry & Drugs

references/pubchem.md

references/chembl.md

references/drugbank.md

references/fda.md

references/dailymed.md

references/kegg.md

references/chebi.md

references/zinc.md

references/bindingdb.md

Materials Science

references/materials-project.md

references/cod.md

Biology & Genomics

references/reactome.md

references/brenda.md

references/uniprot.md

references/string.md

references/ensembl.md

references/ncbi-gene.md

references/ncbi-protein.md

references/ncbi-taxonomy.md

references/geo.md

references/gtex.md

references/pdb.md

references/alphafold.md

references/emdb.md

references/interpro.md

references/biogrid.md

references/gene-ontology.md

references/quickgo.md

references/dbsnp.md

references/sra.md

references/gnomad.md

references/ucsc-genome.md

references/encode.md

references/jaspar.md

references/human-protein-atlas.md

references/hca.md

references/lincs-l1000.md

references/rummageo.md

references/pride.md

references/metabolomics-workbench.md

references/mousemine.md

references/ena.md

references/addgene.md

Disease & Clinical

references/opentargets.md

references/cosmic.md

references/clinpgx.md

references/clinicaltrials.md

references/omim.md

references/clinvar.md

references/tcga-gdc.md

references/cbioportal.md

references/disgenet.md

references/gwas-catalog.md

references/monarch.md

references/hpo.md

Patents & Regulatory

references/uspto.md

references/sec-edgar.md

Economics & Finance

references/fred.md

references/federal-reserve.md

references/bea.md

references/bls.md

references/worldbank.md

references/ecb.md

references/treasury.md

references/alphavantage.md

references/datacommons.md

Social Sciences & Demographics

references/census.md

references/eurostat.md

references/who.md