Executes Cypher queries against Neo4j databases containing the NASA GeneLab Knowledge Graph, enabling natural language querying of differential gene expression, DNA methylation, and other spaceflight experiment data integrated with biomedical knowledge.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP GeneLab Server show me genes upregulated in mouse liver during spaceflight"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that converts natural language queries into Cypher queries and executes them against the configured Neo4j endpoints. Customized tools provide seamless access to the NASA GeneLab Knowledge Graph (spoke-genelab v0.3.1), enabling AI-assisted analysis of spaceflight experiments and their biological effects. This server allows researchers to query differential gene expression, DNA methylation, and differential organism abundance data from NASA's space biology experiments through natural language interactions with AI assistants like Claude.
The GeneLab Knowledge Graph integrates omics data from NASA's Open Science Data Repository (OSDR), with nodes that can be used as connectors to other knowledge graphs, such as the SPOKE (Scalable Precision Medicine Open Knowledge Engine) knowledge graph. This integration connects spaceflight experimental results with a comprehensive biological context, including genes, proteins, anatomical structures, pathways, and diseases.
This server is part of the NSF-funded Proto-OKN Project (Prototype Open Knowledge Network). It's an extension of the Neo4j Cypher MCP server.
Related MCP server: SPARQL MCP Server
The SPOKE-GeneLab KG v0.3.1 contains the following node and relationship types:
Nodes: Study, Mission, Assay, MGene, Gene, MethylationRegion, Organism, Anatomy, CellType
Relationships:
(Mission)-[:CONDUCTED_MIcS]->(Study) — Mission conducted a study
(Study)-[:PERFORMED_SpAS]->(Assay) — Study performed an assay
(Assay)-[:MEASURED_DIFFERENTIAL_EXPRESSION_ASmMG]->(MGene) — Differential gene expression
(Assay)-[:MEASURED_DIFFERENTIAL_METHYLATION_ASmMR]->(MethylationRegion) — Differential methylation
(Assay)-[:MEASURED_DIFFERENTIAL_ABUNDANCE_ASmO]->(Organism) — Differential organism abundance
(Assay)-[:INVESTIGATED_ASiA]->(Anatomy) — Assay investigated an anatomical structure
(Assay)-[:INVESTIGATED_ASiCT]->(CellType) — Assay investigated a cell type
(MGene)-[:IS_ORTHOLOG_MGiG]->(Gene) — Model organism gene is ortholog of human gene
(MGene)-[:METHYLATED_IN_MGmMR]->(MethylationRegion) — Gene is methylated in a region
Natural Language Querying: Ask questions in plain English — no need to write complex graph queries
NASA GeneLab Queries: Ask questions about spaceflight experiments in the NASA GeneLab knowledge graph
Differential Gene Expression Analysis: Find genes that are upregulated or downregulated in spaceflight conditions compared to ground controls
DNA Methylation Data: Access epigenetic changes observed in spaceflight experiments, including promoter / exon / intron / distance-to-feature filtering
Differential Organism Abundance: Query amplicon/metagenomics data showing changes in microbial community composition during spaceflight (DESeq2 and ANCOM-BC method-aware significance filtering)
Cross-Assay Intersection Analyses: Find features differentially detected across multiple assays — common DEGs, common DMRs, common DA organisms — each direction (up/down, hyper/hypo, increased/decreased) kept separate so the LLM can reason about them independently
Expression-Methylation Coupling: Identify differentially expressed genes whose promoter (or other gene region) is also differentially methylated in matched assays; supports pooled DM evidence across multiple methylation assays
Multi-Organism Support: Query data across multiple model organisms including mice, rats, and other species used in space research
Anatomy & Cell Type Filtering: Filter results by specific anatomical structures (UBERON ontology) or cell types (Cell Ontology) used in experiments
Assay Selection: Browse and filter assays by study, organism, technology, or measurement type
Biomedical Context Integration: Connect spaceflight gene expression changes to pathways, diseases, and other biological knowledge from SPOKE
Federated Queries: Combine data from GeneLab with other Neo4j knowledge graphs for comprehensive biomedical analysis
Volcano Plots: Generate volcano plots showing differentially expressed genes / methylated regions / abundant organisms with significance thresholds
Venn Diagrams: Create Venn diagrams comparing differentially expressed genes (or DMRs, or DA organisms) across 2 or 3 assays, including an expression_methylation 2×2 grid variant for paired transcriptomic-epigenomic comparisons
Plot Resource Layer: Every generated plot is exposed as an MCP resource under plot://<filename> and via a fetch_plot tool, so clients can retrieve PNG bytes through a separate request from the tool call that produced them. A failed fetch can be retried without re-running the analysis
Schema Visualization: Generate visual representations of the knowledge graph schema
Mermaid Class Diagrams: Create and clean Mermaid-format class diagrams of the KG schema
Read-Only Enforcement: All Neo4j sessions use READ_ACCESS mode — write operations are rejected at the Bolt protocol level, protecting the knowledge graph from modification
Multiple Transport Modes: Supports STDIO (local), SSE, and Streamable HTTP (remote deployment)
Remote Deployment: Deploy as a web service behind a TLS reverse proxy, accessible via HTTPS URL from any MCP client
Docker Support: Build and deploy as a Docker container for consistent, reproducible environments
Multiple Access Methods: Use through Claude Desktop, VS Code with GitHub Copilot, or any MCP-compatible client
Pre-configured Setup: Ready-to-use mcp-genelab configuration files for a local STDIO connection to the spoke-genelab-v0.3.1 KG (a remote public endpoint is coming soon)
Before using mcp-genelab, ensure you have:
Client Application: One of the following:
Claude Desktop or claude.ai (Pro or Max subscription) — connect via Settings → Connectors → Add Custom Connector
VS Code with GitHub Copilot — connect via MCP server settings
Any MCP client that supports the STDIO or Streamable HTTP transport
Connection to the spoke-genelab-v0.3.1 knowledge graph via one of the two paths below:
For the local STDIO setup you also need:
Operating System: macOS, Linux, or Windows
Python 3.10+ and the uv package manager
Neo4j Desktop with the spoke-genelab-v0.3.1 KG imported (installation links are provided in Option B)
mcp-genelab can be reached two ways: by connecting to the remote public endpoint (coming soon) or by running mcp-genelab locally with STDIO. Both serve the spoke-genelab-v0.3.1 knowledge graph.
Status: Coming soon. A public HTTPS endpoint for mcp-genelab is being prepared. When it is live, the URL will be published here and in the mcp-genelab repository. Until then, use Option B to run mcp-genelab locally.
Once the public endpoint is available, you will be able to connect to mcp-genelab without installing anything locally:
Open Claude Desktop (or claude.ai)
Go to Settings → Connectors (or Manage Connectors)
Click Add Custom Connector
Enter:
Name: mcp-genelab
MCP Server URL: the public mcp-genelab endpoint (coming soon)
Click Save
In the chat prompt, click the + button and toggle the mcp-genelab connector on
Then ask a question like: "What organisms are represented in the spoke-genelab-v0.3.1 knowledge graph?"
Running mcp-genelab locally has two parts: (1) stand up a local Neo4j instance holding the spoke-genelab-v0.3.1 KG, and (2) point mcp-genelab at it via STDIO.
Install Neo4j Desktop and create a spoke-genelab instance (with the APOC plugin) by following the Neo4j Desktop installation instructions.
Import the spoke-genelab-v0.3.1 KG into that instance by following the database import instructions. Name the database exactly spoke-genelab-v0.3.1 and start the instance once the import completes.
Note the Bolt URI (default bolt://localhost:7687), username, and password of your running instance — you will need them in Step 2.
uv and configure mcp-genelabInstall uv if you don't already have it:
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"Then configure your MCP client to launch mcp-genelab over STDIO. For Claude Desktop, go to Claude → Settings → Developer → Edit Config and add the following mcp-genelab entry:
{
"mcpServers": {
"spoke-genelab-local": {
"command": "uvx",
"args": ["mcp-genelab"],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "neo4jdemo",
"NEO4J_DATABASE": "spoke-genelab-v0.3.1",
"INSTRUCTIONS": "Query the spoke-genelab-v0.3.1 KG to identify NASA spaceflight experiments containing omics datasets, specifically differential gene expression (transcriptomics), DNA methylation (epigenomics), and Amplicon (metagenomics) data."
}
}
}
}For VS Code with GitHub Copilot, add the same mcp-genelab entry to your .vscode/mcp.json (note the top-level key is servers, not mcpServers):
{
"servers": {
"spoke-genelab-local": {
"command": "uvx",
"args": ["mcp-genelab"],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "neo4jdemo",
"NEO4J_DATABASE": "spoke-genelab-v0.3.1",
"INSTRUCTIONS": "Query the spoke-genelab-v0.3.1 KG to identify NASA spaceflight experiments containing omics datasets, specifically differential gene expression (transcriptomics), DNA methylation (epigenomics), and Amplicon (metagenomics) data."
}
}
}
}Note: Set
NEO4J_USERNAME,NEO4J_PASSWORD, andNEO4J_URIto match the Neo4j instance you started in Step 1. Theuvxcommand automatically downloads and runs the latest published mcp-genelab from PyPI. KeepNEO4J_DATABASEset tospoke-genelab-v0.3.1to match the database name you imported.
From the top menu bar:
1. Select: Claude->Settings->Connectors
2. Click: Configure for the MCP endpoints you want to use
3. Select Tool permissions: Always allowIn the prompt dialog box, click the + button:
1. Turn off Web search
2. Toggle MCP services on/off as neededUse @kg_name to refer to a specific mcp server (for example, @mcp-genelab).
To create a transcript of a chat (see examples below), use the following prompt:
Create a chat transcript.
The transcript can then be downloaded in .md or .pdf format.
cd mcp-genelab
docker build -t mcp-genelab:latest .docker run \
--name mcp-server \
--publish=127.0.0.1:8000:8000 \
--env NEO4J_URI=bolt://host.docker.internal:7687 \
--env NEO4J_USERNAME=neo4j \
--env NEO4J_PASSWORD=yourpassword \
--env NEO4J_DATABASE=spoke-genelab-v0.3.1 \
--env MCP_TRANSPORT=streamable-http \
--env MCP_HOST=0.0.0.0 \
--env MCP_PORT=8000 \
--detach \
mcp-genelab:latestThe MCP server is then accessible at http://localhost:8000/mcp/.
Variable | Default | Description |
|
| Neo4j Bolt connection URI |
|
| Neo4j username |
|
| Neo4j password |
|
| Neo4j database name for the spoke-genelab-v0.3.1 KG |
|
| Transport mode: |
|
| HTTP listener host (use |
|
| HTTP listener port |
| (see source) | System instructions for the LLM |
Each link below points to a chat transcript that demonstrates how to use the mcp-genelab server to query and analyze GeneLab data hosted in the spoke-genelab-v0.3.1 Neo4j Knowledge Graph.
Overview of spoke-genelab v0.3.1
List spoke-genelab-v0.3.1 assay node, properties, and relationships
OSD-161 DE and spoke-okn disease analysis
Note: To perform this example query, you will need to add the NSF OKN MCP server to your MCP client by following the instructions at https://okn.us/mcp.
The server exposes 22 tools plus a plot://{filename} resource template. Tools are listed below grouped by category. The specialist tools should be preferred over the generic query tool — server.py's DEFAULT_INSTRUCTIONS carries a TOOL SELECTION POLICY that routes natural-language requests to the right specialist.
Tool | Description |
| List all node types, their attributes, and relationships in the knowledge graph |
| Get descriptions of all node types from MetaNode entries |
| Get descriptions of all relationship types and their properties |
| Generate a visual schema diagram of the knowledge graph |
Tool | Description |
| Get detailed information about a specific study and its assays (metadata + assay inventory) |
| Browse and filter assays by study, organism, technology, or measurement; resolve a factor pair to one or more assay IDs |
Tool | Description |
| Find up/downregulated genes for a given assay (DESeq2) |
| Find hyper/hypomethylated regions for a given assay, with optional |
| Find organisms with differential abundance for a given assay (DESeq2 and/or ANCOM-BC) |
Tool | Description |
| Intersect DEGs across multiple assays (up and down directions kept separate) |
| Intersect DMRs across multiple assays, with optional MethylationRegion filters |
| Intersect differentially abundant organisms across multiple assays |
| Identify DE genes whose promoter (or other region) is also differentially methylated — supports method-aware significance filtering and pooled-DM evidence across multiple methylation assays |
Tool | Description |
| Execute a read-only Cypher query on the Neo4j database. Fallback for questions the specialists don't cover — the |
Tool / resource | Description |
| Generate a volcano plot of differential expression / methylation / abundance results; PNG returned inline and registered for resource fetch |
| Create a Venn diagram comparing DEGs / DMRs / DA organisms across 2 or 3 assays (also supports the |
| Re-fetch the canonical PNG bytes of a previously generated plot from the in-memory registry (last 8 plots, FIFO eviction). Returns the bytes as an |
| Return a markdown block with multiple save options for a previously generated plot: right-click save, ask-LLM-client-to-save, or fetch via the |
| MCP resource template — clients fetch PNG bytes via |
Tool | Description |
| Set the user-facing directory where plots and CSV files should be saved |
| Return the currently configured output directory |
Tool | Description |
| Clean and validate a Mermaid class diagram of the KG schema |
| Export the current chat as a formatted transcript |
All Neo4j sessions are opened with default_access_mode=READ_ACCESS, which is enforced at the Bolt protocol level by Neo4j. Any write operation is rejected with the error: "Write operations are not allowed for READ transactions." This works on both Community and Enterprise Edition.
As a second layer of defense, the query tool includes a regex-based write filter (_is_write_query()) that catches the Cypher write keywords MERGE, CREATE, SET, DELETE, REMOVE, ADD, and DROP (case-insensitive) before the query is sent to Neo4j. All queries also use session.execute_read() for transaction-level read enforcement. The two layers — server-side regex + Bolt-level READ_ACCESS — protect the knowledge graph from modification even if one layer is bypassed.
Instructions for local development
The project ships a pytest suite (95 tests across 8 files) that runs offline — no Neo4j connection, no network, no MCP transport. It guards against regressions in tool registration, annotation completeness, routing-policy language in tool docstrings, Cypher invariants (read-only enforcement, conditional LIMIT, lnfc null-safety, MethylationRegion filter propagation, pooled IN $assay_ids clause for cross-assay queries), and the plot resource layer (plot:// URI registration, fetch_plot round-trips, save-instruction size guarantees).
pip install -r mcp-genelab-tests/requirements-test.txt
pytestThe suite runs in roughly 10 seconds and is safe to run on every commit. A GitHub Actions workflow at .github/workflows/test.yml runs the suite on Python 3.10 through 3.13 for every push and pull request. See mcp-genelab-tests/tests/README.md for the per-file breakdown and instructions on adding tests for new tools.
Instructions for building, testing, and publishing the mcp-genelab package on PyPI
MCP server not appearing in Claude Desktop:
Ensure you've completely quit and restarted Claude Desktop (not just closed the window)
Check that your JSON configuration is valid (attach your config file to a chat and ask it to fix any errors)
Verify that uvx is installed and accessible in your PATH
Connection errors:
Verify the Neo4j endpoint URL is correct and accessible
For a local Neo4j Desktop instance, ensure the spoke-genelab instance is started and the spoke-genelab-v0.3.1 database has finished loading
Check that NEO4J_DATABASE is set to spoke-genelab-v0.3.1 and matches the database name you imported
Write operation rejected:
This is expected behavior. All sessions use READ_ACCESS mode. Write operations (CREATE, MERGE, SET, DELETE) are blocked at the Bolt protocol level.
Performance issues:
Complex Cypher queries may take time to execute
Consider breaking down complex queries into smaller parts
Check the endpoint's documentation for query best practices
This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.
If you use MCP GeneLab in your research, please cite the following works:
@software{rose2026mcp-genelab,
title={MCP GeneLab Server},
author={Rose, P.W. and Saravia-Butler, A.M. and Nelson, C.A. and Shi, Y. and Baranzini, S.E.},
year={2026},
url={https://github.com/sbl-sdsc/mcp-genelab}
}
@software{rose2026spoke-genelab,
title={NASA SPOKE-GeneLab Knowledge Graph},
author={Rose, P.W. and Nelson, C.A. and Saravia-Butler, A.M. and Gebre, S.G. and Soman, K. and Grigorev, K.A. and Sanders, L.M. and Costes, S.V. and Baranzini, S.E.},
year={2026},
url={https://github.com/BaranziniLab/spoke_genelab}
}Nelson, C.A., Rose, P.W., Soman, K., Sanders, L.M., Gebre, S.G., Costes, S.V., Baranzini, S.E. (2025). "Nasa Genelab-Knowledge Graph Fabric Enables Deep Biomedical Analysis of Multi-Omics Datasets." NASA Technical Reports, 20250000723. Link
Sanders, L., Costes, S., Soman, K., Rose, P., Nelson, C., Sawyer, A., Gebre, S., Baranzini, S. (2024). "Biomedical Knowledge Graph Capability for Space Biology Knowledge Gain." 45th COSPAR Scientific Assembly, July 13-21, 2024. Link
This work is supported in part by:
National Science Foundation Award #2333819: "Proto-OKN Theme 1: Connecting Biomedical information on Earth and in Space via the SPOKE knowledge graph"
Proto-OKN Project - Prototype Open Knowledge Network initiative
NSF Open Knowledge Network - 40+ interconnected knowledge graphs supported by NSF
NASA Open Science Data Repository (OSDR) - Repository of multi-modal space life science data
NASA GeneLab KG, spoke-genelab - Git Repository for creating the spoke-geneLab KG v0.3.1
Model Context Protocol - AI assistant integration standard
Original Neo4j Cypher MCP server - Base implementation reference
For questions, issues, or contributions, please visit our GitHub repository.
Clean a Mermaid class diagram by removing unwanted elements.
This tool removes:
- All note statements that would render as unreadable yellow boxes
- Empty curly braces from class definitions (handles both single-line and multi-line)
- Strings after newline characters (e.g., truncates "ClassName
extra" to "ClassName")
Args:
mermaid_content: The raw Mermaid class diagram content
Returns:
Cleaned Mermaid content with note statements, empty braces, and post-newline strings removed
| Name | Required | Description | Default |
|---|---|---|---|
| mermaid_content | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the removal operations clearly but doesn't discuss side effects, edge cases, or limitations (e.g., handling of malformed content). It is adequate but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a summary, bullet list, and args/returns, which is helpful. However, it is somewhat verbose (e.g., 'Cleaned Mermaid content with note statements, empty braces, and post-newline strings removed') and could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no annotations), the description covers the basic functionality and return value. However, it lacks completeness regarding expected input format, error handling, or robustness. It meets minimum requirements but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning by specifying 'The raw Mermaid class diagram content' for the single parameter. This goes beyond the schema's minimal definition, though it could provide more format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Clean a Mermaid class diagram by removing unwanted elements.' It lists specific elements removed (note statements, empty curly braces, strings after newline), making the action concrete. Sibling tools are unrelated (creating charts, querying), so it distinguishes well.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when a Mermaid class diagram needs cleaning), but it doesn't explicitly guide usage or mention alternatives. No when-not-to-use advice is given, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prompt for creating a chat transcript in markdown format with user prompts and Claude responses.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose all behavioral traits. It fails to explain how the transcript is generated (e.g., from current session), whether it is written to a file or returned, or any side effects. The wording 'Prompt for creating' is ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is very concise, but slightly ambiguous wording ('Prompt for creating') reduces clarity. Front-loads the action and format, but could be more precise without much length increase.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite simplicity (no parameters, output schema exists), the description omits critical context about how the transcript is sourced or what 'prompt' means. Leaves agent uncertain about invocation without further context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% trivially. Description adds nothing for parameters, but this is acceptable since there are none to describe. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly specifies the tool creates a chat transcript in markdown format with user prompts and Claude responses. It uniquely distinguishes itself from sibling tools which focus on data analysis and visualization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, but the unique purpose makes usage context clear without needing exclusion criteria. A minor gap exists in not stating that this tool likely captures the current conversation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create Venn diagrams comparing differentially expressed genes between 2 or 3 assays.
This function creates side-by-side Venn diagrams showing:
Left: Upregulated genes (log2fc > threshold) overlap
Right: Downregulated genes (log2fc < -threshold) overlap
If assay_id_3 is provided, creates 3-way Venn diagrams. If assay_id_3 is None, creates 2-way Venn diagrams.
Returns a link to the plot and summary statistics. FORMATTING INSTRUCTION: RENDER THE RESPONSE IN MARKDOWN FORMAT!
| Name | Required | Description | Default |
|---|---|---|---|
| assay_id_1 | Yes | First assay identifier (e.g., 'OSD-511-53054e738e335bc645cb620c95916e5f') | |
| assay_id_2 | Yes | Second assay identifier (e.g., 'OSD-511-8974299195d78d74d7f3f085f2b48981') | |
| assay_id_3 | No | Third assay identifier (optional, for 3-way Venn diagram) | |
| log2fc_threshold | No | Log2 fold change threshold for filtering genes | |
| figsize_width | No | Figure width in inches | |
| figsize_height | No | Figure height in inches |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the output (side-by-side Venn diagrams for up and down regulated genes, link to plot, summary statistics) and includes a formatting instruction. No annotations are provided, so the description carries the burden, and it adequately covers behavior without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and clear sections, front-loading the purpose. The FORMATTING INSTRUCTION is somewhat extraneous but not overly verbose. It could be slightly more concise, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no annotations, and an output schema, the description fully covers the behavior, expected input, and output. It explains the up/down regulation logic and return value, making it complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already describes each parameter. The description adds context by explaining the effect of assay_id_3 and the threshold, but this is largely redundant with the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates Venn diagrams for comparing differentially expressed genes between 2 or 3 assays, specifying the up/down regulation distinction. This distinguishes it from siblings like create_volcano_plot and find_common_differentially_expressed_genes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (comparing DE genes) and how the number of assays affects the output (2-way vs 3-way). However, it does not explicitly state when not to use it or compare with alternatives like find_common_differentially_expressed_genes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a volcano plot for differential gene expression data from the given assay.
A volcano plot displays log2 fold change on the x-axis and -log10(adjusted p-value) on the y-axis. Genes are colored based on their significance:
Red: upregulated (log2fc > threshold, adj_p < threshold)
Blue: downregulated (log2fc < -threshold, adj_p < threshold)
Gray: not significant
Returns a link to the plot and summary statistics. FORMATTING INSTRUCTION: RENDER THE RESPONSE IN MARKDOWN FORMAT!
| Name | Required | Description | Default |
|---|---|---|---|
| assay_id | Yes | Assay identifier (e.g., 'OSD-253-6c5f9f37b9cb2ebeb2743875af4bdc86') | |
| log2fc_threshold | No | Log2 fold change threshold for highlighting significant genes | |
| adj_p_threshold | No | Adjusted p-value threshold for significance | |
| top_n | No | How many significant genes to label in the plot | |
| figsize_width | No | Figure width in inches | |
| figsize_height | No | Figure height in inches |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It describes the return value (link and summary statistics) and explains the significance coloring logic. However, it does not disclose potential side effects (e.g., whether it modifies data) or authorization requirements, which are minor omissions given the tool's read-like nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with purpose. The formatting instruction is slightly unnecessary but does not detract significantly from clarity. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but implied by context signals), the description need not detail return values. It covers plot interpretation, threshold logic, and output type. Missing usage guidelines prevent a higher score, but overall it is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 6 parameters have schema descriptions (100% coverage), so the baseline is 3. The tool description adds overall context (e.g., meaning of thresholds) but does not provide additional details per parameter beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that it creates a volcano plot for differential gene expression data, specifying the axes (log2 fold change vs -log10 adjusted p-value) and coloring logic. This distinguishes it from sibling tools like create_venn_diagram or find_differentially_expressed_genes, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for visualizing DE results but does not explicitly state when to use this tool versus alternatives like find_differentially_expressed_genes or create_venn_diagram. No guidance on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find common differentially expressed genes across multiple assays.
This function:
Takes a list of assay IDs as input (2 or more)
Gets ALL genes with |log2fc| > threshold for each assay
Inner joins among the upregulated genes and among the downregulated genes
Returns a markdown table with columns: gene, assay_1, assay_2, ..., assay_n showing log2fc values
FORMATTING INSTRUCTION: RENDER THE RESPONSE IN MARKDOWN FORMAT! INFORM THE USER ABOUT CURRENT THRESHOLDS AND THAT THEY CAN BE CHANGED.
| Name | Required | Description | Default |
|---|---|---|---|
| assay_ids | Yes | List of assay identifiers (e.g., ['OSD-253-abc123', 'OSD-253-def456']) | |
| log2fc_threshold | No | Log2 fold change threshold for filtering genes (default: 1.0 = 2-fold change) | |
| adj_p_threshold | No | Adjusted p-value threshold for significance (default: 0.05, max value: 0.1) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite lacking annotations, the description fully discloses the behavior: it performs inner joins on upregulated and downregulated genes, returns a markdown table with log2fc values, and includes formatting instructions. This covers the tool's non-destructive, read-only nature sufficiently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise intro and numbered steps. It includes useful formatting instructions, though the capitalization in 'FORMATTING INSTRUCTION' is slightly noisy. Overall, it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (so return details are covered), the description is complete. It explains the entire process, threshold usage, and output format, with no observable gaps for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing definitions for each parameter. The description adds value by explaining how thresholds are used in the algorithm (filtering genes) but does not significantly extend beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Find common differentially expressed genes across multiple assays' and explains the step-by-step process, clearly distinguishing it from sibling tools like 'find_differentially_expressed_genes' which likely handle single assays.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that the tool requires 2 or more assay IDs and explains the algorithm, implicitly indicating when to use. It does not explicitly contrast with alternatives or provide 'when not to use' guidance, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the top-N up- and down-regulated genes for a given assay_id.
This tool runs two queries on the GeneLab KG:
Top-N upregulated genes (log2fc > 0, highest first)
Top-N downregulated genes (log2fc < 0, lowest first)
FORMATTING INSTRUCTION: RENDER THE RESPONSE IN MARKDOWN FORMAT!
| Name | Required | Description | Default |
|---|---|---|---|
| assay_id | Yes | Assay identifier (e.g., 'OSD-253-6c5f9f37b9cb2ebeb2743875af4bdc86') | |
| top_n | No | How many genes to return for each of up- and down-regulated lists |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that two separate queries are run, the log2fc filtering criteria, and ordering. It also includes a formatting instruction (render in markdown). While it does not mention side effects or rate limits, for a read-only query tool this level of detail is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences and one formatting instruction. Every sentence adds value—the first states the purpose, the second details the queries, and the instruction ensures proper output. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema (context signal: true), the description is not required to detail return field structure. It adequately explains what is returned (top-N up/down genes) and how they are determined. With an output schema available, this completeness level is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already describes both parameters (assay_id with example, top_n with default). The tool description adds no additional parameter context beyond what the schema provides, so it meets the baseline without exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it returns top-N up- and down-regulated genes for a given assay_id, using two specific queries. This is distinct from sibling tools like create_volcano_plot or find_common_differentially_expressed_genes, so the purpose is clear and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but offers no guidance on when to use it versus alternatives like find_common_differentially_expressed_genes. Usage context is implied by the name and description, but no explicit when-to-use or when-not-to-use information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all nodes, their attributes and their relationships to other nodes in the neo4j database. If this fails with a message that includes "Neo.ClientError.Procedure.ProcedureNotFound" suggest that the user install and enable the APOC plugin.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly indicates the tool is read-only ('list') and provides a failure scenario (APOC missing) with remediation. It lacks details on permission requirements or performance impact, but the core behavioral intent is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences: the first defines the core action, the second provides critical error guidance. No extraneous information, well front-loaded, and every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (which covers return values) and sibling tools, the description adequately explains what the tool does and how to handle a common failure. It could mention that it relies on APOC or that it returns a full graph schema, but this is not critical. The description is complete for its intended scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% and the description does not need to explain parameters. According to guidelines, baseline is 4. The description adds value beyond the schema by explaining the output (nodes, attributes, relationships) and error handling, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all nodes, their attributes and their relationships to other nodes' which is a specific verb-resource pairing. It clearly distinguishes from siblings like get_node_metadata (specific node) and visualize_schema (likely visualization format).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when a full schema listing is needed, and includes a helpful error handling tip for APOC missing. However, it does not explicitly state when to use this tool over alternatives like get_node_metadata or visualize_schema, nor does it provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata for all nodes from MetaNode nodes in the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey all behavioral traits. It only states 'Get metadata' without specifying the nature of the metadata (e.g., fields, format) or any side effects. Since it is a read operation with no parameters, more detail on the output structure would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose. However, it could be slightly expanded with minimal detail about the output without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description is adequate. However, it does not explain what 'MetaNode nodes' are, which may be unclear without domain knowledge. The tool is complete for its narrow scope but could benefit from clarifying the term 'MetaNode'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is no need for parameter descriptions. Schema description coverage is 100% because there are no parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves metadata for all nodes from MetaNode nodes in the knowledge graph. It distinguishes itself from sibling tools like get_neo4j_schema (broader schema) and get_relationship_metadata (focused on relationships) by specifying the exact scope (MetaNode nodes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as query or get_neo4j_schema. The description does not mention any prerequisites, context, or exclusion criteria, leaving the agent to infer usage from the tool's name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get descriptions of properties of all relationships in the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It indicates a read operation returning metadata, but lacks detail on behavior like performance or data scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the presence of an output schema, the description is sufficient to convey the tool's purpose, though additional context about the output format would slightly improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is trivially 100%. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'descriptions of properties of all relationships in the knowledge graph', distinguishing it from sibling tools like 'get_node_metadata' or 'get_neo4j_schema'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of suitable contexts or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a Cypher query on the Neo4j database.
If the question is about up- or down-regulated genes, use the find_upregulated_genes or find_downreguluated genes
EDGE PROPERTIES - CRITICAL: Many relationships in this knowledge graph have properties stored as edge attributes (data ON the relationship itself). Examples include: log2fc, adj_p_value, methylation_diff, q_value, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The Cypher query to execute. | |
| params | No | The parameters to pass to the Cypher query. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that edge properties are on relationships and gives examples, which helps agents understand the data model. However, it does not clarify whether the tool is read-only or can modify data, nor does it mention any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise, with a clear main line and an important note about edge properties. There is a minor typo ('downreguluated'), but overall it is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (return values are covered) and the complexity of the tool, the description adequately highlights the critical edge property context. It could mention that it can be used for arbitrary Cypher queries, but the current content is sufficient for an informed agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters described in schema). The description adds no additional meaning beyond what the schema provides for 'query' and 'params'. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a Cypher query on the Neo4j database,' which is a specific verb and resource. It also distinguishes itself from sibling tools by advising when to use alternatives (find_upregulated_genes, find_downreguluated genes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when not to use this tool (for up/down-regulated genes) and mentions edge properties as critical. However, it does not provide a complete set of when-to-use guidelines or alternatives for other query types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List and select assays for a study and render the response in markdown format.
First call (selection=None):
If study_id missing, prompt for one (e.g., 'OSD-253').
Build a list of unique factor arrays across all assays.
Return a numbered menu as a markdown table!
Second call (selection='i,j,k,l,...,m,n'):
Pairs consecutive indices: (i,j), (k,l), ..., (m,n)
Returns assay_id(s) for each pair comparison
Must provide an even number of indices
FORMATTING INSTRUCTION: RENDER THE RESPONSE IN MARKDOWN FORMAT!
| Name | Required | Description | Default |
|---|---|---|---|
| study_id | No | ||
| selection | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It reveals the interactive, stateful nature (first vs second call), the prompting for study_id if missing, and the pairing of indices. While it doesn't explicitly state read-only or permission requirements, the behavior is well-disclosed for a selection tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy due to detailed step-by-step instructions, but it is well-structured with bullet points and clear sections. Most sentences provide necessary information, though some redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description appropriately avoids detailing return values. It covers the interaction flow, input constraints, and formatting instruction. The description is complete for an agent to understand the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description thoroughly explains both parameters: study_id (if missing, prompt; example given) and selection (string of comma-separated indices, pairs consecutive indices, must be even count). This adds critical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists and selects assays for a study and renders the response in markdown format. The verb 'list and select' combined with the resource 'assays' provides a specific purpose. It also distinguishes from sibling tools, which are focused on different data operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines a two-step process: first call to generate a menu, second call with a selection string. It specifies when to provide study_id, how to format selection, and that an even number of indices is required. This provides clear guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prompt for visualizing the knowledge graph schema using a Mermaid class diagram.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Prompt for visualizing', which suggests it generates a prompt rather than executing directly, but this is not elaborated. With no annotations provided, the description should disclose more behavioral traits such as mutability, permissions, or output format beyond the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key action and tool output. Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool simplicity (zero params, output schema present), the description is minimally adequate. However, it could mention that it generates a Mermaid class diagram and that it is a prompt (not direct execution), to reduce ambiguity with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and the schema coverage is 100%, so baseline is 4. The description adds no parameter information, but none is needed since all parameters are already captured in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('visualizing'), the resource ('knowledge graph schema'), and the method ('Mermaid class diagram'). It distinguishes from sibling tool 'get_neo4j_schema' which retrieves raw schema data, while this tool produces a visual diagram.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'get_neo4j_schema' or 'clean_mermaid_diagram'. The usage is implied but not stated, leaving room for confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.0clean_mermaid_diagramcreate_chat_transcriptcreate_venn_diagramcreate_volcano_plotfind_common_differentially_expressed_genesfind_differentially_expressed_genesget_neo4j_schemaget_node_metadataget_relationship_metadataqueryselect_assaysvisualize_schemaScored across 12 tools
Most tools have clearly distinct purposes, especially the four DEG-related tools (find, common, venn, volcano) each target different outputs. However, 'create_chat_transcript' is an outlier unrelated to gene expression analysis, and 'clean_mermaid_diagram' and 'visualize_schema' both deal with Mermaid diagrams, causing slight ambiguity.
The tools mostly follow a snake_case verb_noun pattern (e.g., clean_mermaid_diagram, select_assays). One exception is 'query', which is just a plain verb without a noun. Overall, the pattern is consistent and predictable.
With 12 tools, the server covers a reasonable scope for a gene expression analysis platform. Each tool contributes to data retrieval, selection, analysis, or visualization, without being overwhelming or too sparse.
Core workflows such as finding differentially expressed genes, comparing assays via Venn diagrams, and generating volcano plots are present. However, the toolset lacks direct support for downloading raw data or exploring beyond the predefined thresholds, and the inclusion of unrelated tools like 'create_chat_transcript' does not fill domain gaps.
Knowledge graph ingestion, entity search, ontology analysis, and CoPass scoring.
Knowledge graph ingestion, entity search, ontology analysis, and CoSync scoring.
Natural-language queries over a verified emissions knowledge graph, plus standards validation
GibsonAI MCP server: manage your databases with natural language
