MaveDB through GeneFoundry

Router invocation: mavedb_get_server_capabilities()

Return the mavedb-link discovery surface: identity/build, the tool list WITH call signatures, response modes, recommended workflows, the MaveDB identifier scheme, the error taxonomy, and limits. detail='full' adds the full policy notes. Call this first in a cold session, or read mavedb://tools / mavedb://capabilities. Signature: get_server_capabilities(detail=).

Router invocation: mavedb_get_diagnostics()

Report upstream MaveDB API reachability and version (live check of GET /api/version), the configured base URL, this build's provenance, and a runtime block (request/error counts and latency percentiles p50/p95/p99). Use this to confirm the API is up or diagnose an upstream_unavailable error. Signature: get_diagnostics().

Router invocation: mavedb_search_score_sets()

Search MaveDB score sets (the datasets carrying scored variants) by free text and facets — target gene(s), organism, target type, and author. Returns score-set hits {urn, title, num_variants, targets, license, ...} plus a pagination block. Organism/target-type facets are null-inclusive by default (records with unknown metadata are KEPT and _meta.facet_excluded reports the drops); pass facet_mode='strict' to also drop unknown-metadata records. This is the MaveDB front door. Signature: search_score_sets(text=, targets=, target_organism_names=, target_types=, authors=, facet_mode=, published=, limit=, offset=, response_mode=).

Router invocation: mavedb_get_score_set()

Return a MaveDB score-set record by URN: title, description, target gene(s) with external IDs, parent experiment, publications, the per-record license, variant count, and (standard/full) dataset columns and method/abstract text. Get the actual scores with get_variant_scores. Signature: get_score_set(urn, response_mode=).

Router invocation: mavedb_get_variant_scores()

Return the quantitative variant-by-variant score table for a score set (urn:mavedb:...-a-1) as parsed rows: each row carries accession, variant_index (numeric join key for get_mapped_variants), HGVS (hgvs_nt/hgvs_splice/hgvs_pro), the numeric score (+ derived classification when calibrated), and score-set specific columns. Paged via offset/limit; NA values become null. Page forward with offset=next_offset. For large pulls use response_mode='minimal' to drop the HGVS columns to {accession, variant_index, score, classification} (token-safe); a full ~1000-row page at standard can exceed the MCP token cap and be auto-saved to a tool-results file — page via offset or use get_score_distribution for summary statistics instead. The top-level calibrations threshold ladder is record-level data shipped once (the first page, start=0) or at full — not re-sent on every forward page; the per-row classification rides on every page. Signature: get_variant_scores(urn, offset=, limit=, drop_na_columns=, response_mode=).

Router invocation: mavedb_get_variant_score()

Look up the functional score for ONE variant without paging the whole table. Pass a full variant URN (urn:mavedb:...-a-1#2) to resolve it directly, OR a score-set URN plus hgvs= (e.g. 'c.8168A>G' or 'p.Arg1699Trp') to scan that score set's table for the matching row(s). BOTH paths return the same shape: {urn, query, resolved_by, match_count, variants:[{variant_urn, variant_index, hgvs_nt, hgvs_pro, score, classifications?}], calibrations?}. mapped_variants are opt-in (standard/full) and current-only unless full. The fast path for 'what is the score (and calibrated class) for this variant?'. Signature: get_variant_score(urn, hgvs=, response_mode=).

Router invocation: mavedb_get_score_distribution()

Summarise a score set's score distribution server-side (MaveDB has no stats endpoint): n, min/max, mean, median, quartiles, stdev, and a 10-bin histogram — a compact summary INSTEAD of paging the whole table. Pass score= to locate that value (its percentile + calibrated classification). Carries the calibration thresholds when present. Signature: get_score_distribution(urn, score=, response_mode=).

Router invocation: mavedb_get_mapped_variants()

Return the genome-mapped GA4GH VRS alleles for a score set's variants (urn:mavedb:...-a-1), each with its source variant URN, variant_index, VRS allele id, ClinGen Allele ID, and current flag — the bridge from assay coordinates to reference-genome/clinical coordinates. Rows are ordered numerically by variant_index to match get_variant_scores, but JOIN on variant_urn/variant_index (do not zip by row — some variants are unmapped). current_only (default true) collapses the current/superseded pair to one row per variant. Paged via offset/limit. Signature: get_mapped_variants(urn, current_only=, limit=, offset=, response_mode=).

Router invocation: mavedb_get_gene_score_sets()

Resolve an HGNC gene symbol (e.g. BRCA1) to its gene identity (name, HGNC id, location) AND every published MaveDB score set that targets it — the COMPLETE set, unioned from HGNC resolution and the target-name facet and deduped by URN (see the coverage block). The fastest complete way to find all MAVE data for a gene. Paged via offset/limit. Signature: get_gene_score_sets(gene_symbol, limit=, offset=, response_mode=).

Router invocation: mavedb_get_experiment()

Return a MaveDB experiment record by URN (urn:mavedb:00000001-a): title, description, parent experiment set, the child score-set URNs, keywords, and publications. An experiment groups one or more score sets from one assay context. Open a child dataset with get_score_set. Signature: get_experiment(urn, response_mode=).

Router invocation: mavedb_search_experiments()

Search MaveDB experiments by free text (author facet, plus target facets — targets/target_organism_names/target_types — derived from the score-set search and grouped by parent experiment). A gene-token query re-ranks experiments whose score sets target the gene above abstract namesakes (reranked_by:'target_gene'). Returns experiment hits {urn, score_set_urns, ...} plus a pagination block (paged client-side). Use search_score_sets when you want datasets/scores; use this for the assay-context grouping. Signature: search_experiments(text=, targets=, target_organism_names=, target_types=, authors=, published=, limit=, offset=, response_mode=).

Router invocation: mavedb_get_collection()

Return a curated MaveDB collection by URN: its name, description, badge, num_score_sets/num_experiments, and the member experiment and score-set URNs. Collections group related datasets (e.g. by gene, consortium, or theme). The member lists are PAGED (limit/offset, truncated/next_offset) so large collections stay light. Open a member with get_score_set. Signature: get_collection(urn, limit=, offset=, response_mode=).

Router invocation: mavedb_find_variant()

Find ONE variant across EVERY MaveDB score set — the same variant's functional measurements wherever it was assayed (the cross-dataset rollup for 'every assay that measured this variant'). Pass variant= in ANY form (auto-detected): a VRS id (ga4gh:VA…), a variant URN ('urn:mavedb:…-a-1#2', resolved to its VRS internally so you do NOT map it first — chain straight from get_variant_score), or a bare HGVS string (+ optional gene_symbol=), resolved to its VRS internally — no map-first round-trip. Each hit carries its score_set_urn, variant_urn, ClinGen Allele ID, and (when enrich=true, default) the score + calibrated classifications. ClinGen Allele IDs are not accepted upstream; pass the variant URN instead. Paged via offset/limit. Signature: find_variant(variant, gene_symbol=, only_current=, enrich=, limit=, offset=, response_mode=).

Router invocation: mavedb_get_hgvs_validation()

Validate an HGVS variant string against MaveDB's validator. Returns {variant, valid, message}: a valid string -> valid=true; a parseable-but-wrong one -> valid=false WITH the upstream reason (e.g. reference-base disagreement, missing transcript accession) so you can fix it before a lookup fails. Not a normalizer. Signature: get_hgvs_validation(variant, response_mode=).

Router invocation: mavedb_get_classified_variants()

Return a score set's variants grouped into a calibrated functional class — e.g. every 'abnormal' (PS3) or 'normal' (BS3) variant — without paging the whole table. Resolves the primary calibration (or a given calibration_urn); filter with classification=abnormal|normal|not_specified (omit for all). Each variant carries its score, HGVS, class label, and ACMG criterion. Paged via offset/limit. Signature: get_classified_variants(urn, classification=, calibration_urn=, limit=, offset=, response_mode=).