AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

database-lookup

Queries documented public database APIs with explicit endpoints, filters, pagination, and provenance. Used when a scientific, regulatory, financial, or other database-backed fact must be retrieved reproducibly from a named source rather than inferred from general knowledge.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--database-lookup at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 83

references/clinvar.md

ClinVar API Reference

Base URLs

  • NCBI E-utilities: https://eutils.ncbi.nlm.nih.gov/entrez/eutils
  • ClinVar web API (VCV): https://www.ncbi.nlm.nih.gov/clinvar
  • NCBI Variation Services: https://api.ncbi.nlm.nih.gov/variation/v0

Authentication

  • E-utilities: No key required, but strongly recommended. Register at https://www.ncbi.nlm.nih.gov/account/ to get an api_key.
  • Without key: 3 requests/second. With key: 10 requests/second.
  • Append &api_key=YOUR_KEY to all E-utility requests.

Rate Limits

  • Without API key: 3 req/sec
  • With API key: 10 req/sec

Key Endpoints

1. Search ClinVar (esearch)

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term={query}&retmode=json

Example — search for BRCA1 pathogenic variants:

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term=BRCA1[gene]+AND+pathogenic[clinical_significance]&retmode=json&retmax=10

Returns JSON with idlist of ClinVar Variation IDs.

2. Fetch ClinVar Records (esummary)

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id={id_list}&retmode=json

Example:

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id=37088,37087&retmode=json

Returns JSON with clinical significance, variant name, gene, conditions, review status.

3. Full Record (efetch)

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=clinvar&id={id}&rettype=vcv&is_variationid&retmode=xml

Note: ClinVar efetch returns XML only (no JSON for efetch).

4. Resolve HGVS/SPDI before searching ClinVar

NCBI Variation Services normalizes variants; it has no /clinvar suffix endpoint. Use GET https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/{hgvs}/contextuals, then /spdi/{spdi}/rsids. Search ClinVar with the resolved rsID (or a validated HGVS expression) using ESearch. An rsID can represent multiple alternate alleles: compare accession, assembly, position and alleles in the ClinVar record. SPDI positions are zero-based; HGVS genomic positions are one-based.

5. ClinVar VCV/RCV Direct Access

GET https://www.ncbi.nlm.nih.gov/clinvar/variation/{variation_id}/?redir=vcv

This returns HTML. For programmatic access, use E-utilities or the Variation Services API.

Useful Search Qualifiers

  • [gene] — gene symbol (e.g., BRCA1[gene])
  • [clinical_significance] — pathogenic, likely_pathogenic, benign, uncertain_significance
  • [molecular_consequence] — missense, nonsense, frameshift, etc.
  • [review_status] — criteria_provided_single_submitter, reviewed_by_expert_panel, etc.
  • [condition] — disease name

Response Format

  • esearch/esummary: JSON (with retmode=json)
  • efetch: XML only for ClinVar
  • Variation Services: JSON

esummary Response Key Fields

{
  "result": {
    "37088": {
      "uid": "37088",
      "title": "NM_003238.6(TGFB2):c.687C>A (p.Cys229Ter)",
      "germline_classification": {
        "description": "Pathogenic",
        "last_evaluated": "2025/09/08 00:00",
        "review_status": "criteria provided, single submitter",
        "fda_recognized_database": "",
        "trait_set": [
          {
            "trait_xrefs": [
              {
                "db_source": "MedGen",
                "db_id": "C3553762"
              },
              {
                "db_source": "MONDO",
                "db_id": "MONDO:0013897"
              },
              {
                "db_source": "OMIM",
                "db_id": "614816"
              }
            ],
            "trait_name": "Loeys-Dietz syndrome 4"
          }
        ]
      },
      "genes": [
        {
          "symbol": "TGFB2",
          "geneid": "7042",
          "strand": "+",
          "source": "submitted"
        }
      ]
    }
  }
}

Somatic clinical impact and oncogenicity are separate classifications; inspect somatic_clinical_impact and oncogenicity when present. Do not conflate these with germline classification or discard conflicting submissions.

Notes

  • Combine esearch + esummary for search-then-fetch workflows.
  • For bulk downloads, use ClinVar FTP: https://ftp.ncbi.nlm.nih.gov/pub/clinvar/