get_open_targets_graphql_schema
Retrieve the Open Targets Platform GraphQL schema filtered by category.
You MUST specify one or more categories to retrieve the relevant schema subset.
Categories group related GraphQL types into coherent subschemas
(e.g., 'drug-mechanisms', 'genetic-associations', 'target-safety').
The returned schema includes types from the specified categories plus
their dependencies expanded.
Args:
categories: List of category names to filter the schema. At least
one category must be specified.
Returns:
str: the schema text in SDL (Schema Definition Language) format.
Raises:
RuntimeError: If schema was not pre-fetched at startup.
ValueError: If an invalid category name is provided.
Examples:
- get_open_targets_graphql_schema(["drug-mechanisms"]) -> drug types
- get_open_targets_graphql_schema(["target-safety", "drug-safety"])
-> combined safety-related types
Available categories:
- cancer-genomics: Cancer-specific genomic evidence from Cancer Gene Census, IntOGen, cancer biomarkers databases, and cancer hallmarks. Identifies cancer driver genes and somatic mutations.
- clinical-genetics: Clinical genetics databases and rare disease evidence from ClinGen, ClinVar, Genomics England PanelApp, Orphanet, and Gene2Phenotype. Provides clinical validity of gene-disease relationships, pathogenic variants, and clinical genomics panels.
- comparative-genomics: Cross-species comparative genomics and orthology relationships for leveraging model organism data. Shows evolutionary conservation and functional predictions based on homology.
- disease-associations: Target-disease association evidence and target prioritisation, integrating evidence across multiple data types. Shows the strength of association between genes/targets and diseases and the target prioritisation factors that can be used to prioritise targets for further investigation.
- disease-phenotypes: Disease phenotypes, symptoms, and ontology for understanding clinical manifestations, disease classifications, and relationships between different conditions.
- drug-indications: Approved and investigational drug indications, clinical trial phases, mechanism-based predictions for drug repurposing, and known drug-disease relationships.
- drug-mechanisms: Drug mechanisms of action and target interactions from ChEMBL, including drug-target relationships, polypharmacology profiles, and molecular mechanisms of therapeutic effects.
- drug-safety: Post-market drug safety and pharmacovigilance data from FDA FAERS, including adverse events, drug warnings, and safety alerts for approved medications.
- entity-search: Cross-entity search and entity discovery across all entity types with keyword search capabilities. Enables finding targets, diseases, drugs, variants, and studies by name or identifier.
- experimental-models: Experimental model organism data including CRISPR knockout screens, mouse phenotypes from IMPC, cancer cell line dependency from DepMap, and chemical probes. Provides functional validation data from laboratory experiments.
- functional-genomics: Gene expression, biological pathways, and systems biology data from Expression Atlas, Reactome, Gene Ontology. Provides context on gene function, regulation, and pathway involvement.
- genetic-associations: Genome-wide association studies (GWAS) and molecular QTL associations. Returns GWAS summary statistics, shared trait studies, and disease-associated genetic variants from population-scale studies. Fine-mapping results and credible set analysis from GWAS and QTL studies. Includes locus-to-gene predictions, colocalization analyses, and probabilistic identification of causal variants.
- genetic-constraint: Genetic constraint metrics. Measures selection pressure on genes including loss-of-function intolerance, showing which genes are essential for survival.
- literature-evidence: Scientific literature and bibliographic data, including disease and drug bibliographies. Supports text-mined evidence and citation networks.
- molecular-interactions: Protein-protein interactions and molecular networks for understanding biological context, cellular pathways, and functional relationships between biomolecules.
- pharmacogenomics: Genetic variation affecting drug response, including gene-drug interactions, genotype-dependent efficacy or toxicity, and personalized medicine applications.
- platform-metadata: Platform metadata including version information, data release prefix, and metadata on all downloadable datasets. Also includes metadata on Open Targets (OTAR) projects (if available).
- protein-information: Protein abundances and subcellular localization data.
- target-safety: Target safety liabilities and toxicity predictions based on adverse events, animal toxicology, and clinical safety flags. Assesses potential risks of modulating a therapeutic target.
- target-tractability: Target druggability and tractability assessments, including small molecule and antibody tractability predictions. Evaluates the likelihood of successfully developing drugs against a target.
- variant-annotation: Variant functional annotation and population genetics. Includes variant effect predictions (VEP), European Variation Archive data, UniProt variant annotations, and predicted functional consequences of genetic variation.
get_type_dependencies
Get schema subsets for types, separated by specific and shared deps.
Given a list of type names, returns SDL (Schema Definition Language)
organized into type-specific dependencies and shared dependencies.
Returns a dict with:
- One key per input type: SDL for types ONLY reachable from that type
- "shared" key: SDL for types reachable from multiple input types
Examples:
- get_type_dependencies(["Target"]) - All deps under "Target" key
- get_type_dependencies(["Target", "Drug"]) - Separated + shared
Args:
type_names: List of GraphQL type names to start exploration from
Returns:
dict with type-specific SDL and shared SDL
Raises:
ValueError: If any type_name is not found in the schema
search_entities
Search for entities across multiple types using the Open Targets Platform search API.
This tool performs a streamlined entity search that returns the id and entity type
for up to 3 matching entities across targets, diseases, drugs, variants, and studies.
Supports multiple query strings in a single call - each query is executed independently
and results are returned in a dictionary keyed by the query string.
Args:
query_strings: List of search queries (e.g., ["BRCA1", "breast cancer", "aspirin"])
Returns:
dict: Dictionary mapping each query string to its results (array of up to 3 entities
with id and entity fields), or error message if any query fails.
Example:
Input: ["BRCA1", "aspirin"]
Output: {
"BRCA1": [
{"id": "ENSG00000012048", "entity": "target"},
{"id": "EFO_0000305", "entity": "disease"}
],
"aspirin": [
{"id": "CHEMBL25", "entity": "drug"}
]
}
query_open_targets_graphql
Execute GraphQL queries against the Open Targets Platform API.
WORKFLOW - Follow these steps in order:
Step 1: RESOLVE IDENTIFIERS
If user provides common names (gene symbols, disease names, drug names),
use `search_entity` tool FIRST to convert them to standardized IDs:
- Targets/Genes: "BRCA2" -> ENSEMBL ID "ENSG00000139618"
- Diseases: "breast cancer" -> EFO/MONDO ID "MONDO_0007254"
- Drugs: "aspirin" -> ChEMBL ID "CHEMBL1201583"
- Variants: Use "chr_pos_ref_alt" format or rsIDs
Example: search_entity(query_string="BRCA2", entity_names=["target"])
Step 2: LEARN QUERY STRUCTURE
Call `get_open_targets_graphql_schema` with relevant categories to retrieve
the schema subset needed for your query. Select categories that cover the
data domains you need - BE INCLUSIVE (it's better to include extra categories
than to miss required types).
Example: For a query about drug mechanisms and safety:
get_open_targets_graphql_schema(categories=["drug-mechanisms", "drug-safety"])
Study the returned schema to understand available types, fields, and their
relationships, then construct a GraphQL query that fetches the information
the user needs.
FALLBACK: If you encounter errors or need detailed information about specific
types, use `get_type_dependencies` sparingly to explore type relationships.
This tool provides exhaustive type dependency information but should only be
used when category-based retrieval is insufficient.
Step 3: CONSTRUCT AND EXECUTE QUERY
Build GraphQL query using:
- Standardized IDs from Step 1 (REQUIRED)
- Query structure from Step 2
- Follow the "COMMON MISTAKES TO AVOID" guidance in the schema output
Call this tool with query_string and optional variables.
REQUIRED IDENTIFIER FORMATS:
- Targets/Genes: ENSEMBL IDs (e.g., "ENSG00000139618")
- Diseases: EFO IDs (e.g., "EFO_0000305") or MONDO IDs (e.g., "MONDO_0007254")
- Drugs: ChEMBL IDs (e.g., "CHEMBL1201583")
- Variants: "chr_pos_ref_alt" format (e.g., "19_44908822_C_T") or rsIDs (e.g., "rs7412")
- Studies: Study IDs (e.g., "GCST90002357")
- Credible Sets: Study Locus IDs (e.g., "7d68cc9c70351c9dbd2a2c0c145e555d")
Args:
query_string: GraphQL query starting with 'query' keyword
variables: Optional dict or JSON string with query variables
Returns:
dict: GraphQL response with data field containing targets, diseases, drugs, variants,
studies or error message.
batch_query_open_targets_graphql
Execute the same GraphQL query multiple times with different variable sets.
Use this tool instead of the regular query tool when you need to run the same query
repeatedly with different arguments (e.g., querying multiple drugs, targets, or diseases).
WORKFLOW - Follow these steps in order:
Step 1: RESOLVE IDENTIFIERS
If user provides common names (gene symbols, disease names, drug names),
use `search_entity` tool FIRST to convert them to standardized IDs:
- Targets/Genes: "BRCA1", "BRCA2" -> ENSEMBL IDs "ENSG00000012048", "ENSG00000139618"
- Diseases: "breast cancer" -> EFO/MONDO ID "MONDO_0007254"
- Drugs: "aspirin", "ibuprofen" -> ChEMBL IDs "CHEMBL1201583", "CHEMBL521"
- Variants: Use "chr_pos_ref_alt" format or rsIDs
Example: search_entity(query_string="BRCA1 BRCA2", entity_names=["target"])
Step 2: LEARN QUERY STRUCTURE
Call `get_open_targets_graphql_schema` with relevant categories to retrieve
the schema subset needed for your query. Select categories that cover the
data domains you need - BE INCLUSIVE (it's better to include extra categories
than to miss required types).
Example: For a query about drug mechanisms and safety:
get_open_targets_graphql_schema(categories=["drug-mechanisms", "drug-safety"])
Study the returned schema to understand available types, fields, and their
relationships, then construct a GraphQL query that fetches the information
the user needs.
FALLBACK: If you encounter errors or need detailed information about specific
types, use `get_type_dependencies` sparingly to explore type relationships.
This tool provides exhaustive type dependency information but should only be
used when category-based retrieval is insufficient.
Step 3: CONSTRUCT AND EXECUTE BATCH QUERY
Build GraphQL query and variables_list using:
- Standardized IDs from Step 1 (REQUIRED)
- Query patterns from Step 2
- Follow the "COMMON MISTAKES TO AVOID" guidance in the schema output
Call this tool with query_string, variables_list, and key_field.
REQUIRED IDENTIFIER FORMATS:
- Targets/Genes: ENSEMBL IDs (e.g., "ENSG00000139618")
- Diseases: EFO IDs (e.g., "EFO_0000305") or MONDO IDs (e.g., "MONDO_0007254")
- Drugs: ChEMBL IDs (e.g., "CHEMBL1201583")
- Variants: "chr_pos_ref_alt" format (e.g., "19_44908822_C_T") or rsIDs (e.g., "rs7412")
- Studies: Study IDs (e.g., "GCST90002357")
- Credible Sets: Study Locus IDs (e.g., "7d68cc9c70351c9dbd2a2c0c145e555d")
Args:
query_string: The GraphQL query string to execute for all variable sets
variables_list: List of variable dictionaries, one per query execution
key_field: Variable field name to use as key in results mapping (e.g., "chemblId")
Returns:
dict: Results keyed by the specified field value, with execution summary:
{
"status": "success",
"results": {
"<key_value>": {"status": "success", "data": ...},
...
},
"summary": {"total": <int>, "successful": <int>, "failed": <int>}
}