Open Targets Platform MCP

Official

Overview Schema Source Related Servers Discussions Admin

batch_query_open_targets_graphql

Read-only

Execute the same GraphQL query with multiple variable sets to retrieve Open Targets data for many drugs, targets, or diseases in a single batch.

Instructions

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 (str): The GraphQL query string to execute for all variable sets. variables_list (list[dict[str, Any]]): List of variable dictionaries, one per query execution. key_field (str): Variable field name to use as key in results mapping.

Returns: (BatchQueryResult): Results keyed by the specified field value, with execution summary.

Input Schema

TableJSON Schema

Name	Required	Description
`key_field`	Yes	Variable field name to use as key in results mapping.
`query_string`	Yes	The GraphQL query string to execute for all variable sets.
`variables_list`	Yes	List of variable dictionaries, one per query execution.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`results`	Yes
`status_counts`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 15, 2026

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true, so the safety profile is already established. The description adds meaningful behavioral context: it reveals that one query_string is executed for all variable sets, that results are keyed by the specified field value, and that an execution summary is returned. This goes beyond the bare read-only annotation without contradicting it, though it does not mention rate limits, concurrency, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with marked steps, bullet lists, and examples. It front-loads the purpose and then organizes prerequisite actions logically. It earns its length given the tool's complexity, though the Args section repeats schema descriptions and the workflow could be slightly tightened without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a complex orchestration tool, and the description covers the full workflow: identifier resolution, schema retrieval, fallback dependency exploration, query construction, and execution. It lists required identifier formats and references common-mistakes guidance from the schema output. Since an output schema exists, return value details are already covered externally. An agent has everything needed to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by specifying required identifier formats (ENSEMBL, ChEMBL, MONDO, rsIDs, chr_pos_ref_alt) and giving usage examples with search_entity. It also clarifies the role of key_field as the mapping key for results, which is more concrete than the schema's brief description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb/resource: 'Execute the same GraphQL query multiple times with different variable sets.' It clearly differentiates from the 'regular query tool' by naming the condition (repeated execution with different arguments). The batch behavior is unambiguous and distinct from siblings like query_open_targets_graphql.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this tool instead of the regular query tool when you need to run the same query repeatedly with different arguments.' It goes further with a step-by-step workflow, telling when to use search_entity, get_open_targets_graphql_schema, and get_type_dependencies as a fallback. This is exactly the kind of when/when-not/alternatives guidance that helps an agent decide correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server