Tools Reference
The MCP server exposes four tools. A typical analysis uses three of them in sequence — resolve metadata, start the analysis, then poll for results. The remaining tool,get_counts_data_url, is a utility for downloading the raw
counts data when you want to work with it outside the chat.
resolve_sample_metadata
Resolves a natural-language experiment description into structured sample groups for downstream analysis. Always call this beforeanalyze_gene_expression.
Parameters
Response
Returns one of three shapes depending on status: Complete — metadata extraction succeeded; review before proceeding.resolution_id.
Warnings
Thewarnings array flags issues such as drugs or compounds that were not found
in the ontology. Review warnings before proceeding — they may indicate a
misspelling or an unsupported perturbation.
analyze_gene_expression
Starts the differential gene expression analysis pipeline from a confirmed resolution.Parameters
Response
job_id, call get_analysis_results immediately to begin
polling.
get_analysis_results
Polls the status of a running analysis. Each call waits server-side for up to approximately 40 seconds and may return earlier if progress is detected. Call this immediately afteranalyze_gene_expression and again after each response —
no client-side delay is needed.
Parameters
Response
Running — the pipeline is still executing. Call again immediately.```json block holding
up to 1,000 of the most significant differentially expressed genes returned
by the backend. Parse the JSON block directly to drive downstream analysis or
visualization (e.g. a volcano plot with x = log2FoldChange, y = -log10(padj)).
Failed — the pipeline encountered an error.
Pipeline stages
The analysis moves through two major computation stages:- GEM model (
gem_model) — AI-powered gene expression model inference for the requested sample groups. - Differential expression (
diff_expr) — Welch’s t-test with Benjamini-Hochberg false discovery rate correction on the top 10,000 most variable genes.
Result shape
When the pipeline completes, the response embeds the analysis summary in Markdown and a fenced```json block with up to 1,000 of the most
significant gene-level results. The summary fields (ok, reference_level,
test_level, total_samples, total_genes_tested, significant_genes,
significant_up, significant_down) are rendered as a Markdown bullet list;
the gene-level array is the canonical structured payload for downstream LLM
consumption:
The analysis performs one pairwise comparison. With exactly two groups this is
the full comparison. With three or more groups the analysis compares the first
two alphabetically — remaining groups are ignored.
get_counts_data_url
Returns a presigned download URL for the raw gene expression counts data generated by a completed analysis job. The file is large (tens of MB) and should be processed with external tools such ascurl or Python — not loaded
into the conversation.
Parameters
Response
Returns a presigned URL for the counts JSON (valid for 1 hour), a second presigned URL for the model’s gene-symbol-mapping Parquet, the modality, sample group names, sample counts per group, and documentation of the data format.Data format
The downloaded JSON file contains:gene_order— array of ~20,000 Ensembl gene IDs.outputs— one entry per sample, withcountsaligned togene_order.model_version— the GEM model version used.
Gene symbol mapping
Alongside the counts URL, the response includes a presigned URL for a small (~500 KB) Parquet file with two columns:gene_id— the Ensembl ID (matches an entry ingene_order).gene_name— the HGNC gene symbol (e.g.TP53).
gene_id to label genes by symbol: