gnomAD through GeneFoundry

Router invocation: gnomad_get_server_capabilities()

Use this when a client needs supported tools, datasets, population codes, recommended workflows, the live ClinVar release date, or current limitations. Returns ~7kB.

Router invocation: gnomad_get_variant_frequencies()

Use this when a caller has a fully-resolved CHROM-POS-REF-ALT id and needs allele counts/frequencies per population. Pair with get_clinvar_variant_details for clinical context. Compact defaults trim subcohort and zero-AC rows; toggle the boolean flags to expand, or use response_mode='full' for the most-inclusive breakdown or response_mode='minimal' for just the headline + overall/max-pop summary. Returns a `truncated` block when filters drop rows so the LLM can re-call with explicit overrides. Returns ~2-4kB (minimal ~0.6kB).

Router invocation: gnomad_get_variant_details()

Use this when a caller needs transcript consequences or in-silico predictors for a single variant id. This tool does NOT return ClinVar clinical significance — for that call get_clinvar_variant_details. Prefer get_variant_frequencies if only allele counts are needed; this tool returns the larger annotation payload. Compact trims the exome/genome population breakdown (drops subcohort, sex-split, and zero-AC rows; toggle the booleans to expand) and emits a `truncated` block per source. Returns compact ~3-6kB, full up to ~50kB.

Router invocation: gnomad_compare_variant_across_datasets()

Use this when a caller wants to see how one variant's allele frequencies shift across gnomAD releases (r4 vs r3 vs r2_1) and which populations diverge most. Datasets that lack the variant are marked present=false (partial success); the GRCh37 gnomad_r2_1 leg is auto-lifted from the GRCh38 id. Pair with get_clinvar_variant_details for clinical context. Compact (default) drops the per-dataset population arrays (comparison.per_population_af_deltas keeps the per-pop AFs); response_mode='full' returns the raw rows. Returns ~2-4kB compact, ~3-8kB full.

Router invocation: gnomad_compute_carrier_frequency()

Use this when a caller needs an estimated carrier/affected frequency derived from a single gnomAD allele frequency under Hardy-Weinberg assumptions for AR, AD, or X-linked inheritance. Pure local math on top of get_variant_frequencies; returns a one-line `headline`, Wilson 95% CIs, per-population breakdown, and provenance (short citations + a gnomad://citations pointer in compact mode; full citations with response_mode='full'). Estimates are research-use only, never clinical decision support. Returns ~2-4kB.

Router invocation: gnomad_get_gene_details()

Use this when a caller has a gene id or symbol and needs constraint scores (pLI/oe_lof), canonical transcript, and basic coordinates. Follow with get_gene_variants if they then need per-variant rows. Returns compact ~2kB, full up to ~30kB.

Router invocation: gnomad_get_gene_variants()

Use this when a caller wants per-variant rows for an Ensembl gene. Caps large results at 500; consequence/AF/AC filters and include_populations control payload size. Reports cap use in `truncated` and describes retained population fields in `population_projection`. Returns ~5-45kB at the default limit=100.

Router invocation: gnomad_compute_gene_carrier_frequency()

Use this when a caller needs gene-level autosomal-recessive carrier frequency across qualifying pathogenic variants, not a single variant. Run this server-side computation once per gene; do not loop over variants. Returns global and per-population carrier frequency, genetic and Bayesian prevalence, a headline, provenance, and contributing variants. Research use only; not clinical decision support. Returns ~4-30kB (gene/limit dependent).

Router invocation: gnomad_get_gene_summary()

Use this when a caller wants a one-shot gene dossier: constraint (pLI/oe_lof), canonical and MANE-Select transcripts, top pathogenic ClinVar variants, and expression (mean pext + top GTEx tissues). Pass a gene symbol (e.g. PCSK9) or Ensembl gene ID (ENSG...). Use include_clinvar / include_constraint / include_expression to fetch only the sections you need (e.g. include_clinvar=false + include_constraint=false for expression-only). Follow with get_gene_variants for per-variant rows. Returns compact ~3-8kB (ClinVar-dependent); include_clinvar=false trims it most.

Router invocation: gnomad_get_clinvar_variant_details()

Use this when a caller needs ClinVar clinical significance, review status, gold stars, or submissions for a single variant id. Complementary to get_variant_frequencies for clinical workflows. compact (default) drops per-submission provenance bookkeeping; response_mode='full' keeps it. Returns ~2-8kB compact, larger with full or a high submissions_limit.

Router invocation: gnomad_get_clinvar_meta()

Use this when a caller only needs the ClinVar release date or revision currently served by gnomAD -- cheaper than full capabilities. Returns <1kB. DEPRECATED: prefer get_server_capabilities.

Router invocation: gnomad_compute_variant_liftover()

Use this when a caller has a variant id in one reference build and needs the equivalent id in the other. Works BOTH directions (GRCh37<->GRCh38); the converted coordinate is in each result's `target_variant_id` (and `target_reference_genome` names the build). Use this BEFORE calling frequency tools if the dataset and coordinate build do not match. Returns <1kB.

Router invocation: gnomad_get_region()

Use this when a caller wants genes and/or ClinVar variants in a small region (<=100kb). Spans larger than 100kb are clamped and a `truncated` block reports it. Per-category caps (`max_clinvar_variants`, `max_genes`) keep payload bounded; surplus rows are summarised in a `truncated_payload` block. For per-variant SNV listings use get_gene_variants instead. Returns ~5-30kB at compact defaults; up to ~50kB with compact_rows=False.

Router invocation: gnomad_get_coverage()

Use this when a caller needs gnomAD read-depth coverage for a gene, region, or single variant. Pass ONE target — a gene symbol, Ensembl gene ID, region (chr-start-stop), or variant (CHROM-POS-REF-ALT) — and the scope is auto-detected. Gene/region return per-position bins plus a {mean_coverage, fraction_over_20} summary; variant returns scalar coverage. Compact mode trims each bin and caps bin count. Returns ~3-40kB compact (bin-count dependent), larger with response_mode='full'.

Router invocation: gnomad_get_structural_variant()

Use this when a caller has a gnomAD structural variant id (deletions, duplications, inversions, translocations/BND, complex/CPX, MCNV). SV ids come from search_structural_variants (search a gene/region first); they are NOT resolvable by resolve_variant_id, which is SNV/indel only. For SNVs/indels use get_variant_frequencies instead. Compact (default) drops heavy histograms + the duplicated flat gene list and emits a `truncated` block; response_mode='full' returns everything. Returns compact ~2-5kB; full ~10-20kB (histograms + populations).

Router invocation: gnomad_get_mitochondrial_variant()

Use this when a caller has a mitochondrial variant id (M-POS-REF-ALT). Mitochondrial ploidy and heteroplasmy fields are returned; for autosomal variants use get_variant_frequencies. By default zero-count heteroplasmy bins are trimmed and a `truncated.kind=heteroplasmy_zeros` block reports the count; set `include_heteroplasmy_zeros=True` to keep them. Returns ~2-4kB.

Router invocation: gnomad_get_transcript_details()

Use this when a caller has an Ensembl transcript id and needs exon structure and (by default) a compact GTEx tissue-expression summary for that transcript. GTEx is sourced via the gene path; the lookup is best-effort, so exon structure is returned even if expression is unavailable. For gene-level info use get_gene_details. Returns ~3-8kB (set include_expression=False to skip GTEx).

Router invocation: gnomad_search_structural_variants()

Use this when a caller wants the list of structural variants overlapping a gene or region. Pass ONE target — a gene symbol, Ensembl gene ID, or region (CHROM-START-STOP) — and the scope is auto-detected. SV variant_id values are OPAQUE (e.g. DEL_19_1), NOT CHROM-POS-REF-ALT, so no SNV id grammar is applied; fetch a single SV by id with get_structural_variant. sv_dataset is the DISTINCT structural-variant dataset enum (gnomad_sv_r4=GRCh38 default, gnomad_sv_r2_1=GRCh37), not the SNV dataset. Type/length filters are applied client-side. An empty match is a success with returned=0, not an error. Returns ~3-30kB (limit-dependent).

Router invocation: gnomad_search_genes()

Use this when a caller has a fuzzy gene query (symbol, alias, partial name). Follow with get_gene_details for full constraint metrics. Note: gnomAD's gene autocomplete returns a bounded set and may omit exact members of a large gene family for a SHORT prefix (e.g. 'GRIN' does not return GRIN1/GRIN2B). If an expected gene is missing, query its FULL symbol (e.g. 'GRIN1') or call get_gene_details/get_gene_summary directly. Returns ~1-3kB.

Router invocation: gnomad_resolve_variant_id()

Use this when the caller only has an rsID, partial coordinates, or text fragment and needs to obtain a canonical gnomAD variant id. With enrich=True (default) the top hits include gene_symbol, major_consequence, and AF so the caller can rank candidates without a follow-up call. Returns ~1-5kB (enrichment dependent).

Router invocation: gnomad_search_variants()

Use this when a caller uses the legacy tool name -- deprecated alias for resolve_variant_id. Mirrors the same enrichment behaviour; will be removed in the next release. Returns ~1-5kB (deprecated alias).

Router invocation: gnomad_get_diagnostics()

Use this when an LLM hits repeated errors or needs server health information; returns recent error history, server version, upstream availability flag, and recent_schema_drift entries so an LLM that hit output_validation_failed can self-diagnose. Returns <1kB.