Civic Tools

Configuration File: civic_tools.json Tool Type: Local Tools Count: 12

This page contains all tools defined in the civic_tools.json configuration file.

Available Tools

civic_get_assertion (Type: CIViCTool)

Get one CIViC assertion by id, with THE EVIDENCE IT IS MADE FROM. Returns the assertion’s type, d…

civic_get_assertion tool specification

Tool Information:

• Name: civic_get_assertion

• Type: CIViCTool

• Description: Get one CIViC assertion by id, with THE EVIDENCE IT IS MADE FROM. Returns the assertion’s type, direction, significance, AMP/ASCO/CAP tier, variant origin, FDA companion-test and regulatory-approval flags with the dates they were last checked, NCCN guideline, ACMG and ClinGen codes, phenotypes, disease, therapies, molecular profile, the curator flagged flag – and evidenceItems, every evidence item the assertion cites, each with its own level, type, direction, significance, rating, status, disease, therapies and source. Check each item’s status: an assertion can cite an item that was later REJECTED.

Parameters:

• assertion_id (integer) (required) CIViC assertion ID (e.g., 101)

Example Usage:

query = {
    "name": "civic_get_assertion",
    "arguments": {
        "assertion_id": 10
    }
}
result = tu.run(query)

civic_get_evidence_item (Type: CIViCTool)

Get one CIViC evidence item by id, with THE ASSERTIONS THAT CITE IT. Returns the evidence level, …

civic_get_evidence_item tool specification

Tool Information:

• Name: civic_get_evidence_item

• Type: CIViCTool

• Description: Get one CIViC evidence item by id, with THE ASSERTIONS THAT CITE IT. Returns the evidence level, type, direction, significance and curator rating, the disease (with DOID), therapies, phenotypes, molecular profile, the curator flagged flag, a fully resolvable source (citationId is the PMID for PUBMED sources, with retraction status and date), and assertions – each assertion built on this item, with its status, type, direction, significance, AMP tier and FDA/regulatory flags.

Parameters:

• evidence_id (integer) (required) CIViC evidence item ID (e.g., 116)

Example Usage:

query = {
    "name": "civic_get_evidence_item",
    "arguments": {
        "evidence_id": 10
    }
}
result = tu.run(query)

civic_get_molecular_profile (Type: CIViCTool)

Get detailed information about a specific molecular profile in CIViC database by molecular profil…

civic_get_molecular_profile tool specification

Tool Information:

• Name: civic_get_molecular_profile

• Type: CIViCTool

• Description: Get detailed information about a specific molecular profile in CIViC database by molecular profile ID. Molecular profiles represent combinations of variants or features (e.g., ‘BRAF V600E’) that serve as biomarkers for clinical interpretation. Associated evidence is cursor-paginated: when metadata.evidence_has_more is true, pass metadata.next_evidence_cursor as evidence_after to retrieve the next page.

Parameters:

• molecular_profile_id (integer) (required) CIViC molecular profile ID (e.g., 12 for BRAF V600E)

• evidence_limit (integer) (optional) Maximum number of evidence items to return on this page (default: 10, maximum: 100)

• evidence_after ([‘string’, ‘null’]) (optional) Opaque evidence cursor from metadata.next_evidence_cursor.

Example Usage:

query = {
    "name": "civic_get_molecular_profile",
    "arguments": {
        "molecular_profile_id": 10
    }
}
result = tu.run(query)

civic_get_variant (Type: CIViCTool)

Get one CIViC variant by id, including its MyVariant.info annotation. Returns the variant’s name,…

civic_get_variant tool specification

Tool Information:

• Name: civic_get_variant

• Type: CIViCTool

• Description: Get one CIViC variant by id, including its MyVariant.info annotation. Returns the variant’s name, aliases, types, feature, genomic coordinates (with reference build and coordinate type), ClinVar ids, HGVS descriptions, allele registry id, MANE Select transcript, OpenCRAVAT link, its molecular profiles – and deprecated, deprecationReason and flagged, so a retired or flagged variant is distinguishable from a current one. myVariantInfo carries 62 annotation fields: gnomAD and ExAC allele frequencies, pathogenicity predictors with both score and call (SIFT, PolyPhen-2, PROVEAN, FATHMM, MutationTaster, MutationAssessor, MetaSVM, MetaLR, LRT, CADD, REVEL, fitCons), conservation (GERP, phyloP, phastCons, SiPhy), and dbSNP, COSMIC and ClinVar cross-references. No other tool in the catalogue exposes it.

Parameters:

• variant_id (integer) (required) CIViC variant ID (e.g., 4170)

• molecular_profile_limit (integer) (optional) Maximum associated molecular profiles to return on this page (default: 5, maximum: 100)

• molecular_profile_after ([‘string’, ‘null’]) (optional) Opaque continuation cursor from metadata.next_molecular_profile_cursor.

Example Usage:

query = {
    "name": "civic_get_variant",
    "arguments": {
        "variant_id": 10
    }
}
result = tu.run(query)

civic_get_variants_by_gene (Type: CIViCTool)

Get variants associated with a specific gene in CIViC. Returns variant IDs, names, the exact tota…

civic_get_variants_by_gene tool specification

Tool Information:

• Name: civic_get_variants_by_gene

• Type: CIViCTool

• Description: Get variants associated with a specific gene in CIViC. Returns variant IDs, names, the exact totalCount, and cursor pagination metadata. Use gene_name or gene_symbol (e.g., ‘EGFR’, ‘BRAF’) for convenience, or gene_id if already known. When metadata.has_more is true, pass metadata.next_cursor as after to retrieve the next page.

Parameters:

• gene_id (integer) (optional) CIViC gene ID (e.g., 19 for EGFR, 12 for BRAF). Find gene IDs using civic_search_genes.

• gene_name (string) (optional) Gene symbol (e.g., ‘EGFR’, ‘BRAF’, ‘TP53’). Will be looked up automatically. Aliases: gene, gene_symbol, query.

• gene_symbol (string) (optional) Alias for gene_name. Standard gene symbol (e.g., ‘KRAS’, ‘BRCA1’, ‘EGFR’).

• gene (string) (optional) Alias for gene_name. Gene symbol (e.g., ‘EGFR’, ‘KRAS’).

• limit (integer) (optional) Maximum number of variants to return (default: 500, uses cursor pagination to bypass CIViC’s 100/page server cap)

• after ([‘string’, ‘null’]) (optional) Opaque CIViC continuation cursor. Pass metadata.next_cursor from the preceding call with the same gene filter.

Example Usage:

query = {
    "name": "civic_get_variants_by_gene",
    "arguments": {
    }
}
result = tu.run(query)

civic_search_assertions (Type: CIViCTool)

Search CIViC assertions with exact totalCount and cursor pagination. Each row carries the asserti…

civic_search_assertions tool specification

Tool Information:

• Name: civic_search_assertions

• Type: CIViCTool

• Description: Search CIViC assertions with exact totalCount and cursor pagination. Each row carries the assertion’s type, direction, significance, AMP/ASCO/CAP tier (ampLevel), variant origin, evidence count, disease (with DOID), therapies and molecular profile, so a result set can be triaged without a civic_get_assertion call per row. When metadata.has_more is true, pass metadata.next_cursor as after with the same filters.

Parameters:

• limit (integer) (optional) Maximum number of assertions to return (default: 20, recommended max: 100)

• after ([‘string’, ‘null’]) (optional) Opaque continuation cursor from metadata.next_cursor.

• therapy (string) (optional) Filter by therapy/drug name (e.g., ‘imatinib’, ‘ponatinib’). Alias: therapy_name.

• therapy_name (string) (optional) Alias for therapy. Filter by therapy/drug name.

• disease (string) (optional) Filter by disease name (e.g., ‘leukemia’, ‘melanoma’). Alias: disease_name.

• disease_name (string) (optional) Alias for disease. Filter by disease name.

• variant_name (string) (optional) Filter by variant name (e.g., ‘V600E’, ‘T315I’).

Example Usage:

query = {
    "name": "civic_search_assertions",
    "arguments": {
    }
}
result = tu.run(query)

civic_search_diseases (Type: CIViCTool)

Search CIViC’s disease list by name substring. Each disease returns its id, name, display name, D…

civic_search_diseases tool specification

Tool Information:

• Name: civic_search_diseases

• Type: CIViCTool

• Description: Search CIViC’s disease list by name substring. Each disease returns its id, name, display name, DOID, aliases, link, deprecation flag, and HOW MUCH IS ATTACHED TO IT: evidenceItemCount, assertionCount, variantCount and featureCount – the numbers that make a result list usable, since ‘Melanoma’ matches nine CIViC diseases whose evidence ranges from 304 items to 1. The connection reports filteredCount (how many diseases match) beside totalCount (how many CIViC holds in all). The match is a case-insensitive substring of the name, not an ontology lookup: it does not walk the Disease Ontology, so a subtype whose name does not contain the string is not returned, and several unrelated diseases that happen to share a word are.

Parameters:

• limit (integer) (optional) Maximum number of diseases to return (default: 20, recommended max: 100)

• after ([‘string’, ‘null’]) (optional) Opaque continuation cursor from metadata.next_cursor.

• name (string) (optional) Filter by disease name (e.g., ‘leukemia’, ‘melanoma’, ‘lung cancer’). Alias: query.

• query (string) (optional) Alias for name. Filter by disease name.

Example Usage:

query = {
    "name": "civic_search_diseases",
    "arguments": {
    }
}
result = tu.run(query)

civic_search_evidence_items (Type: CIViCTool)

Search CIViC evidence items with exact totalCount and cursor pagination. Each row carries the evi…

civic_search_evidence_items tool specification

Tool Information:

• Name: civic_search_evidence_items

• Type: CIViCTool

• Description: Search CIViC evidence items with exact totalCount and cursor pagination. Each row carries the evidence level, type, direction, significance and curator rating, the disease (with DOID), therapies and molecular profile, and a resolvable source: citationId (the PMID for PUBMED sources), title, journal, year, URL, and whether the publication has been RETRACTED. When metadata.has_more is true, pass metadata.next_cursor as after with the same filters. The disease filter is a name substring that unions every matching CIViC disease; metadata.disease_filter names the ones present in the page returned.

Parameters:

• limit (integer) (optional) Maximum evidence items to return across server pages (default: 20, max: 1000).

• status ([‘string’, ‘null’]) (optional) Filter by curation status. Default: ACCEPTED (peer-reviewed). Options: ACCEPTED, SUBMITTED, REJECTED, ALL (returns all statuses combined).

• therapy (string) (optional) Filter by therapy/drug name (e.g., ‘imatinib’, ‘pembrolizumab’). Alias: therapy_name. Note: matches any evidence item where the therapy appears, including combination regimens — results may include multi-drug combinations.

• therapy_name (string) (optional) Alias for therapy. Filter by therapy/drug name.

• disease (string) (optional) Filter by disease NAME (e.g. ‘leukemia’, ‘melanoma’, ‘lung cancer’). Alias: disease_name. This is a case-insensitive SUBSTRING MATCH that UNIONS every CIViC disease whose name contains it – ‘Melanoma’ returns 235 evidence items drawn from seven diseases (Melanoma, Skin Melanoma, Uveal, Acral Lentiginous, Mucosal, Spitzoid, Malignant Anus Melanoma), which is neither Melanoma’s own 304 nor any ontology subtree. It does not expand subtypes either: a related disease whose name does not contain the string is absent. metadata.disease_filter lists the diseases actually present in the page returned; call civic_search_diseases with the same string for the full match list with each disease’s evidenceItemCount. CIViC uses specific names (‘Lung Non-small Cell Carcinoma’, not ‘NSCLC’).

• disease_name (string) (optional) Filter by disease NAME (e.g. ‘leukemia’, ‘melanoma’, ‘lung cancer’). Alias: disease_name. This is a case-insensitive SUBSTRING MATCH that UNIONS every CIViC disease whose name contains it – ‘Melanoma’ returns 235 evidence items drawn from seven diseases (Melanoma, Skin Melanoma, Uveal, Acral Lentiginous, Mucosal, Spitzoid, Malignant Anus Melanoma), which is neither Melanoma’s own 304 nor any ontology subtree. It does not expand subtypes either: a related disease whose name does not contain the string is absent. metadata.disease_filter lists the diseases actually present in the page returned; call civic_search_diseases with the same string for the full match list with each disease’s evidenceItemCount. CIViC uses specific names (‘Lung Non-small Cell Carcinoma’, not ‘NSCLC’).

• molecular_profile (string) (optional) Filter by molecular profile name (e.g., ‘BRAF V600E’, ‘EGFR T790M’, ‘KRAS G12C’). Uses substring matching — ‘FLT3 ITD’ will also match ‘FLT3 ITD AND FLT3 D835Y’. For gene fusions, CIViC uses double-colon notation: ‘GENE::PARTNER Fusion’ (e.g., ‘FGFR2::BICC1 Fusion’, ‘ALK::EML4 Fusion’). Use civic_search_molecular_profiles to discover exact profile names. Gene-prefixed clinical spellings (‘EGFRvIII’, ‘BRAFV600E’) are also handled: CIViC names the profile ‘<gene> <designation>’ (‘EGFR VIII’), so that separated form is queried too and both result sets are merged, reported in normalization_note.

• evidence_type ([‘string’, ‘null’]) (optional) Filter by evidence type. Values: PREDICTIVE (drug response), DIAGNOSTIC (disease diagnosis), PROGNOSTIC (patient outcomes), PREDISPOSING (disease risk), ONCOGENIC (variant pathogenicity), FUNCTIONAL (molecular function).

• significance ([‘string’, ‘null’]) (optional) Filter by clinical significance. Values depend on evidence_type, e.g. SENSITIVITYRESPONSE, RESISTANCE (predictive); BETTER_OUTCOME, POOR_OUTCOME (prognostic); POSITIVE, NEGATIVE (diagnostic); ONCOGENIC, PROTECTIVE. Use to separate, e.g., resistance from sensitivity evidence for a variant.

• after (string) (optional) Opaque CIViC continuation cursor from a previous pageInfo.endCursor.

• evidence_direction ([‘string’, ‘null’]) (optional) Filter by evidence direction.

Example Usage:

query = {
    "name": "civic_search_evidence_items",
    "arguments": {
    }
}
result = tu.run(query)

civic_search_genes (Type: CIViCTool)

Search for genes in CIViC (Clinical Interpretation of Variants in Cancer) database. Returns exact…

civic_search_genes tool specification

Tool Information:

• Name: civic_search_genes

• Type: CIViCTool

• Description: Search for genes in CIViC (Clinical Interpretation of Variants in Cancer) database. Returns exact totalCount and cursor pagination metadata. When metadata.has_more is true, pass metadata.next_cursor as after with the same gene filter.

Parameters:

• limit (integer) (optional) Maximum number of genes to return (default: 10, recommended max: 100)

• after ([‘string’, ‘null’]) (optional) Opaque continuation cursor from metadata.next_cursor.

• name (string) (optional) Gene symbol to search for (e.g., “EGFR”, “BRAF”, “BRCA1”). Alias: use ‘query’ or ‘gene_name’ instead.

• query (string) (optional) Gene symbol to search for (e.g., “FLT3”, “KRAS”, “TP53”). Alias for ‘name’.

• gene_name (string) (optional) Gene symbol to search for. Alias for ‘name’.

Example Usage:

query = {
    "name": "civic_search_genes",
    "arguments": {
    }
}
result = tu.run(query)

civic_search_molecular_profiles (Type: CIViCTool)

Search CIViC molecular profiles with exact totalCount and cursor pagination. When metadata.has_mo…

civic_search_molecular_profiles tool specification

Tool Information:

• Name: civic_search_molecular_profiles

• Type: CIViCTool

• Description: Search CIViC molecular profiles with exact totalCount and cursor pagination. When metadata.has_more is true, pass metadata.next_cursor as after.

Parameters:

• limit (integer) (optional) Maximum number of molecular profiles to return (default: 20, recommended max: 100)

• after ([‘string’, ‘null’]) (optional) Opaque continuation cursor from metadata.next_cursor.

• query (string) (optional) Filter by molecular profile name (e.g., ‘BRAF V600E’, ‘EGFR T790M’, ‘FLT3 ITD’). Returns profiles whose name contains this string. Alias: ‘name’.

• name (string) (optional) Alias for query. Filter by molecular profile name (e.g., ‘PD-L1’, ‘KRAS G12C’).

Example Usage:

query = {
    "name": "civic_search_molecular_profiles",
    "arguments": {
    }
}
result = tu.run(query)

civic_search_therapies (Type: CIViCTool)

Search CIViC therapies with cursor pagination. CIViC publishes no filter-aware total for this bro…

civic_search_therapies tool specification

Tool Information:

• Name: civic_search_therapies

• Type: CIViCTool

• Description: Search CIViC therapies with cursor pagination. CIViC publishes no filter-aware total for this browse table, so metadata.has_more is the completeness signal; continue with metadata.next_cursor as after while has_more is true.

Parameters:

• limit (integer) (optional) Maximum number of therapies to return (default: 20, recommended max: 100)

• after ([‘string’, ‘null’]) (optional) Opaque continuation cursor from metadata.next_cursor.

• name (string) (optional) Filter by therapy/drug name (e.g., ‘imatinib’, ‘ponatinib’, ‘pembrolizumab’). Alias: query.

• query (string) (optional) Alias for name. Filter by therapy/drug name.

Example Usage:

query = {
    "name": "civic_search_therapies",
    "arguments": {
    }
}
result = tu.run(query)

civic_search_variants (Type: CIViCTool)

Search for variants in CIViC database. The tool follows CIViC’s 100-record GraphQL pages up to li…

civic_search_variants tool specification

Tool Information:

• Name: civic_search_variants

• Type: CIViCTool

• Description: Search for variants in CIViC database. The tool follows CIViC’s 100-record GraphQL pages up to limit and returns exact totalCount plus pageInfo. If pageInfo.hasNextPage is true, pass pageInfo.endCursor as after to continue. Use query to search by variant name, or gene/gene_name to get variants for a gene.

Parameters:

• limit (integer) (optional) Maximum number of variants to return across server pages (default: 20, max: 1000).

• query (string) (optional) Variant name to search for (e.g., “T790M”, “V600E”, “exon 19 deletion”). Returns name-matching variants.

• gene (string) (optional) Gene symbol to filter variants by (e.g., ‘EGFR’, ‘BRAF’, ‘KRAS’). Returns all variants for that gene.

• gene_name (string) (optional) Alias for gene. Gene symbol (e.g., ‘TP53’, ‘BRCA1’).

• variant_name (string) (optional) Specific variant name to filter within a gene (e.g., ‘L858R’, ‘V600E’, ‘T790M’). Use together with gene_name — CIViC stores variants without the gene prefix (use ‘L858R’ not ‘EGFR L858R’). Gene-prefixed clinical spellings (‘EGFRvIII’, ‘BRAFV600E’) are still handled: the gene-stripped designation is queried as well and both result sets are merged, reported in normalization_note.

• after (string) (optional) Opaque CIViC continuation cursor from a previous pageInfo.endCursor.

Example Usage:

query = {
    "name": "civic_search_variants",
    "arguments": {
    }
}
result = tu.run(query)

Navigation

• Available Tools - Back to Tools Overview

• Tool Loading Tutorial - Loading Local Tools