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., "@geo-mcp search for GEO datasets related to breast cancer"
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.
Status: Beta. The MCP stdio and HTTP servers are both functional and in day-to-day use. The public tool surface is stable for the 0.1.x line; internal APIs and config defaults may still evolve. Please open an issue if you hit a regression.
A Model Context Protocol (MCP) server for accessing GEO (Gene Expression Omnibus) data through NCBI E-Utils API. The tool will enable you to search for GEO datasets, series, samples, platforms, and profiles for your LLM. Tested with Claude Desktop, chatGPT has no out of the box support for this tool yet. Claude will automatically use the tools if it fits the context.
install from pip
pip install geo-mcpinstall from source
git clone https://github.com/MCPmed/GEOmcp
cd GEOmcp
pip install -e .Related MCP server: NCBI Entrez MCP Server
Run init to create a config file
geo-mcp --initBy default this writes to $XDG_CONFIG_HOME/geomcp/config.json
(typically ~/.config/geomcp/config.json). If you already have a legacy
~/.geo-mcp/config.json from an older install, that location is still
honored and --init will update it in place so nothing gets orphaned.
The file contains:
{
"base_url": "https://eutils.ncbi.nlm.nih.gov/entrez/eutils",
"email": "your_email@example.com",
"api_key": "YOUR_API_KEY",
"download_dir": "~/.local/share/geomcp/downloads"
}email is required by NCBI.
api_key is optional but recommended for higher rate limits
(get one here).
You can also skip the config file entirely and pass values via env vars
(GEOMCP_EMAIL, GEOMCP_API_KEY, GEOMCP_BASE_URL, GEOMCP_DOWNLOAD_DIR)
or CLI flags (--email, --api-key, --download-dir, ...). Precedence,
highest wins: CLI flags → env vars → config.json → built-in defaults.
MCP stdio mode:
geo-mcpHTTP mode:
geo-mcp --http --port 8001spawn geo-mcp ENOENTThis error means Claude Desktop cannot find the geo-mcp command. This is usually a PATH issue.
Find the full path to the executable:
which geo-mcpExample output: /Users/youruser/miniforge3/bin/geo-mcp
Update your Claude config:
Instead of just "geo-bio-mcp", use the full path:
{
"mcpServers": {
"geo-mcp": {
"command": "/Users/youruser/miniforge3/bin/geo-mcp",
"env": {
"CONFIG_PATH": "/Users/youruser/.geo-mcp/config.json"
}
}
}
}(Optional) Use a Conda Environment:
Activate your conda env and run which geo-mcp to get the correct path.
Use that path in your Claude config as above.
Restart Claude Desktop after updating the config.
If you see command not found: geo-mcp, make sure you installed into the
Python environment whose bin directory is on your PATH, or invoke the
server with its full path.
If the config file is missing, geo-mcp --init will create one. You can
also run without a config by setting GEOMCP_EMAIL in the environment.
With the server running via geo-mcp --http (default port 8001), the
following endpoints are exposed:
GET / — server status
GET /health — health check
GET /tools — list all registered MCP tools
POST /tools/call — execute a tool with arguments
GET /events — server-sent events stream of tool calls
GET /docs — interactive Swagger UI
# List available tools
curl http://localhost:8001/tools
# Search GEO Series
curl -X POST http://localhost:8001/tools/call \
-H "Content-Type: application/json" \
-d '{
"name": "search_geo_series",
"arguments": {"term": "breast cancer", "retmax": 5}
}'This MCP server provides access to all major GEO databases through the following tools:
search_geo - Universal GEO search across GSE/GSM/GPL/GDS records, with
results bucketed by accession type. Pass record_types to filter.
Example searches: "breast cancer", "GSE12345", "RNA-seq time course"
search_geo_profiles - Search gene expression profiles across different biological contexts
Example searches: "cancer", "breast cancer", "p53", "apoptosis"
search_geo_datasets - Search curated gene expression datasets
Example searches: "diabetes", "Alzheimer's disease", "drug response", "tissue specific"
search_geo_series - Search original submitter-supplied gene expression series
Example searches: "GSE12345", "microarray", "RNA-seq", "time course"
search_geo_samples - Search individual gene expression samples
Example searches: "GSM123456", "human", "mouse", "tumor", "normal"
search_geo_platforms - Search microarray platform definitions
Example searches: "Affymetrix", "Illumina", "Agilent", "GPL96"
Each tool accepts:
term (required): Search term or query string
retmax (optional, default: 20): Maximum number of results to return
For now just chat with claude desktop and it will use the tools automatically if it fits the context.
User: find a small brain dataset
Assistant: I'll help you find a small brain dataset from the GEO database. Let me search for brain-related datasets with a maximum of one result.
Assistant (system): search_geo_datasets
Assistant: I found a brain-related dataset for you:
Dataset: GSE290848
Title: Maternal Stress Triggers Early-Life Eczema via Fetal Mast Cell Reprogramming [10x Genomics Multiome ATAC + Gene Expression]
Species: Mouse (Mus musculus)
Samples: 8
Data type: ATAC-seq & gene expression (10x Genomics Multiome)
Publication date: 21 Jun 2025
This small dataset explores how prenatal stress affects neuro-immune circuits and mast-cell development.
Would you like me to download this dataset or search for others?
User: download GSE290848
Assistant: I'll download the GSE290848 dataset for you.
Assistant (system): download_geo_data
Assistant: Download complete.
Downloaded files
GSE290848_family.soft.gz — series, platform & sample info
GSE290848_metadata.xml — detailed study metadata
Location: ~/.local/share/geomcp/downloads/gse/GSE290848
Total size: 0.01 MB
The dataset is ready for analysis. Let me know if you’d like to explore it further.
Clean up downloaded files
| Name | Required | Description | Default |
|---|---|---|---|
| geo_id | No | Optional specific GEO ID to remove | |
| db_type | No | Optional database type filter for cleanup |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It does not disclose whether the tool modifies or deletes data, what happens to files, or any side effects. 'Clean up' implies destructive action but lacks explicit confirmation, risking misuse.
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 short sentence, which is concise, but it omits crucial context. While it avoids fluff, it under-specifies the tool's behavior, making it less useful than a slightly longer but more informative description.
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 no annotations and no output schema, the description must compensate. It fails to specify the scope of cleanup (e.g., all downloaded files vs. selective), whether it's reversible, or if user confirmation is needed. The two optional parameters suggest selectivity, but the description remains too vague.
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%, and each parameter already has a description in the schema. The tool's description adds no additional meaning beyond 'clean up downloaded files', so the 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 'Clean up downloaded files' uses a clear verb ('clean up') and resource ('downloaded files'), but it's vague about what exactly is cleaned (e.g., temporary files, cached data). It does not distinguish from siblings like 'download_geo_data' or 'get_download_stats', but the purpose is generally understandable.
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. The description does not mention prerequisites, when cleanup is appropriate, or when to avoid it. With zero sibling differentiation, the agent receives no help in deciding to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download GEO data files (SOFT format)
| Name | Required | Description | Default |
|---|---|---|---|
| geo_id | Yes | GEO accession ID (e.g., GSE12345, GSM789, GPL456, GDS123) | |
| db_type | No | Database type: gse, gsm, gpl, or gds (default: gse) | gse |
| output_dir | No | Optional custom output directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It only mentions downloading SOFT format, but does not disclose side effects (e.g., overwriting files, network usage, or error handling). Essential behavioral traits like what happens if the output directory exists are omitted.
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 sentence that is appropriately sized and front-loaded. It contains no unnecessary words, though it could benefit from slightly more detail without becoming verbose.
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 lack of output schema, the description should explain what the tool returns or achieves. It does not mention the result (e.g., file path, success message), leaving the agent uncertain about the tool's output. The description is incomplete for a tool with no structured output documentation.
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 covers all parameters with descriptions, so the description adds little beyond what is already known. The term 'SOFT format' provides some context, but does not significantly enhance parameter understanding.
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 'Download GEO data files (SOFT format)', which specifies the verb and resource. It distinguishes itself from sibling tools like search and management tools, but lacks additional context such as the purpose of SOFT 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?
No guidance on when to use this tool versus alternatives (e.g., when to choose different db_type or how the tool relates to search tools). The description does not mention prerequisites or typical usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get download statistics and limits
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It implies a read operation but does not mention side effects, permissions, or return behavior. Minimal transparency beyond the basic purpose.
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, efficient sentence with no unnecessary words. It is well-structured for quick understanding.
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?
With no output schema and no annotations, the description is insufficient. It does not explain what statistics or limits are returned, leaving the agent without critical information about the tool's output.
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 schema coverage is 100%. Baseline for 0 parameters is 4, and the description adds no parameter details, which is acceptable since none exist.
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 'download statistics and limits', specifying the action and resource. It distinguishes from sibling tools like 'cleanup_downloads_tool' and 'get_download_status' which focus on different 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?
No guidance is provided on when to use this tool vs alternatives like 'get_download_status'. The description lacks explicit context or exclusions, leaving the agent to infer usage without support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a GEO dataset has been downloaded
| Name | Required | Description | Default |
|---|---|---|---|
| geo_id | Yes | GEO accession ID | |
| db_type | No | Database type: gse, gsm, gpl, or gds (default: gse) | gse |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only says 'check if downloaded' but does not describe idempotency, network requirements, or what the output contains. This is insufficient for a status check 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 a single front-loaded sentence with no wasted words. It is appropriately concise for a simple tool.
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 low complexity, the description lacks crucial context about the return value (e.g., boolean, status), which is essential since no output schema exists. It also does not position itself relative to 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?
Schema coverage is 100% with adequate parameter descriptions. The tool description adds no additional meaning beyond what the schema provides, meeting the baseline for fully documented parameters.
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 checks if a GEO dataset has been downloaded, using a specific verb and resource. It distinguishes from siblings like download_geo_data and list_downloaded_datasets.
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 the tool is used to verify download status but does not explicitly state when to use it versus alternatives like get_download_stats or list_downloaded_datasets. No when-not guidance 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 downloaded GEO datasets
| Name | Required | Description | Default |
|---|---|---|---|
| db_type | No | Optional filter by database type: gse, gsm, gpl, or gds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it provides only the core purpose. It does not mention whether the operation is read-only, how results are ordered, or any constraints (e.g., session 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?
Single sentence, front-loaded, with no extraneous information. Every word 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?
For a simple list tool with one optional parameter, the description provides basic understanding but omits details like output format, ordering, or what constitutes 'downloaded'. Lacks completeness for an agent without additional 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?
Schema coverage is 100%, so the parameter 'db_type' is fully described in the schema. The tool description does not add extra meaning beyond the schema, yielding a baseline score of 3.
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 'List all downloaded GEO datasets' clearly states the verb (List) and resource (downloaded GEO datasets), distinguishing it from sibling tools that perform searches, downloads, or cleanup.
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 like search_geo or get_download_stats. The description only states the function, leaving the agent to infer usage context from tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GEO for all types of records (GSE, GSM, GPL, GDS)
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term (e.g., 'breast cancer', 'GSE12345', 'RNA-seq') | |
| retmax | No | Maximum number of results to return (default: 20) | |
| record_types | No | Filter for specific record types: GSE, GSM, GPL, GDS |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description should compensate. It lacks any behavioral details such as whether the search is read-only, rate limits, pagination behavior, or what happens on no results. Extremely limited.
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, no wasted words. Efficient for conveying the core purpose, but could sacrifice a bit of conciseness for more context.
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?
With no output schema and no behavioral transparency, the description is insufficient for agents to understand return format, pagination, or limitation. Sibling tools exist but no usage guidance is provided.
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% with parameter descriptions. However, the description adds no extra meaning beyond the schema; it merely repeats that the tool searches all types.
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 searches GEO for all record types, listing them explicitly. It distinguishes from sibling tools by using 'all types' versus their specific types.
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 more specific siblings like search_geo_series or search_geo_samples. Adding context like 'Use this for broad searches across all record types; use specific tools for targeted queries' would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GEO Datasets (GDS) - curated gene expression datasets
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term for GEO Datasets | |
| retmax | No | Maximum number of results to return (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavioral traits. It only states it performs a search, but does not disclose aspects like pagination behavior, result ordering, potential latency, or any side effects. For a search tool, the lack of transparency into result handling is a notable gap.
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 sentence that is front-loaded with the action and resource. It is efficient and to the point, though it could include slightly more useful detail without becoming verbose.
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?
The tool has a simple, two-parameter input and no output schema. The description does not explain what the output contains (e.g., list of dataset summaries). For a tool with no output schema, the description should at least hint at the return format. The lack of completion leaves agents uncertain about the tool's 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?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond the schema. Baseline score of 3 is appropriate for this coverage level.
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 'Search' and the resource 'GEO Datasets (GDS)', and the parenthetical 'curated gene expression datasets' further specifies the content. It effectively distinguishes from sibling tools like search_geo_samples, search_geo_platforms, etc., each targeting different GEO sub-resources.
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 siblings. The description does not include any context about prerequisites, preferred scenarios, or exclusions. Given the multiple similar search tools, this omission impairs tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GEO Platforms (GPL) - array/sequencing platforms
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term for GEO Platforms | |
| retmax | No | Maximum number of results to return (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must convey behavioral traits. It only states the search action, with no mention of side effects, authentication, rate limits, or read-only nature. This is insufficient for a tool that likely has a similar behavior to other search tools.
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 at one sentence. It is front-loaded with the purpose. However, it lacks sufficient detail, which lowers score slightly.
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 multiple sibling search tools, the description does not help an agent differentiate when to use this one. No output schema or behavioral hints. The tool is simple but incompletely described for context-aware selection.
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% as both parameters have descriptions in the schema. The tool description adds no additional meaning beyond the schema, so baseline 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 it searches GEO Platforms (GPL) for array/sequencing platforms. However, it does not differentiate from sibling search tools like search_geo_datasets or search_geo_series, which serve similar search functions for other GEO entities.
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 over siblings. No conditions, exclusions, or references to alternative tools are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GEO Profiles database for gene expression profiles
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term for GEO Profiles | |
| retmax | No | Maximum number of results to return (default: 20) |
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 only states that the tool searches for profiles, but omits details such as pagination (though retmax is documented in schema), error handling, response format, or any side effects. The description adds minimal behavioral context beyond the basic purpose.
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, efficient sentence that conveys the core purpose without extraneous words. It is appropriately front-loaded and fits within expected length for a simple search tool.
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 complexity (2 parameters, no output schema, no annotations), the description is adequate but minimal. It does not clarify the scope of results, data source, or integration with other GEO tools. While sufficient for a straightforward search, more context would be beneficial for agent understanding.
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%, so the schema already documents both parameters. The description does not add any additional meaning or usage advice beyond what the schema provides. The baseline score of 3 is appropriate as the description neither adds nor detracts significantly from the parameter documentation.
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 'Search', the target resource 'GEO Profiles database', and the object 'gene expression profiles'. This specifically distinguishes it from sibling tools like search_geo_datasets, search_geo_platforms, etc., which target different GEO sub-databases.
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 like search_geo or search_geo_datasets. There is no mention of prerequisites, restrictions, or typical use cases, leaving the agent uninformed about selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GEO Samples (GSM) - individual samples
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term for GEO Samples | |
| retmax | No | Maximum number of results to return (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It only says 'Search' without disclosing results behavior, authentication needs, rate limits, or data completeness.
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 short sentence, very concise and front-loaded. It contains no unnecessary words, though it could be slightly more informative 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?
While the tool is simple (2 params, no output schema), the description lacks details about return format, result limitations, or usage tips. Given the numerous siblings, more context would help an agent select correctly.
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?
Both parameters are fully described in the input schema (100% coverage), and the description adds no additional meaning beyond what the schema provides. 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 searches GEO Samples (GSM) and specifies 'individual samples', which distinguishes it from siblings like search_geo_datasets or search_geo_series. The verb 'Search' combined with the resource 'GEO Samples' provides specific purpose.
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 the many sibling search tools (e.g., search_geo_datasets, search_geo_series). There is no mention of context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GEO Series (GSE) - complete experiments
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term for GEO Series | |
| retmax | No | Maximum number of results to return (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully convey behavioral traits, but it only states 'Search GEO Series'. It does not disclose expected behavior such as result format, pagination (though retmax exists), rate limits, or whether it requires network access. The agent is left unaware of key operational details.
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: a single phrase. It is front-loaded with the key action and resource. While it lacks structural elements like full sentences, it is not verbose and gets the core idea across efficiently.
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 only 2 parameters, no annotations, and no output schema, the description is insufficiently complete. It does not explain what results look like, whether they include metadata or just identifiers, or how to interpret the output. The presence of many sibling tools further demands differentiation that is missing.
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% (both term and retmax have descriptions), so the baseline is 3. The description adds no extra meaning beyond the schema, such as example term formats or the impact of retmax on result truncation.
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 'Search GEO Series (GSE) - complete experiments', making clear the tool searches for GEO Series entities. The phrase 'complete experiments' provides additional context, but it does not explicitly differentiate from sibling tools like search_geo_datasets or search_geo_samples, which search related but distinct entity types.
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 the many sibling search tools (e.g., search_geo, search_geo_datasets). There is no mention of typical use cases or when to prefer one over another, leaving the agent to infer based solely on entity names.
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.1.0cleanup_downloads_tooldownload_geo_dataget_download_statsget_download_statuslist_downloaded_datasetssearch_geosearch_geo_datasetssearch_geo_platformssearch_geo_profilessearch_geo_samplessearch_geo_seriesScored across 11 tools
Each tool targets a distinct resource or action: search tools are differentiated by GEO record type (series, samples, platforms, datasets, profiles) plus a general search; download and management tools are clearly distinct (download, stats, status, list, cleanup). No overlapping purposes.
Most tools follow a consistent verb_noun pattern (e.g., download_geo_data, search_geo_series). The outlier is cleanup_downloads_tool, which uses 'cleanup' instead of 'clean' and has a '_tool' suffix, breaking the pattern slightly.
11 tools is well-scoped for a GEO MCP server, covering search across key record types, download operations, and dataset management. The number feels appropriate—neither too few nor excessive.
The server provides comprehensive search, download, and management capabilities for GEO data. Potential gaps include the absence of an explicit delete operation for individual datasets (cleanup is a blanket operation) and lack of upload or update functionality, but these are peripheral to the primary purpose.
Search biomedical literature, get article details, find related articles, and explore MeSH terms
Search 36M+ PubMed biomedical articles and ClinicalTrials.gov studies.
Search PubMed/Europe PMC, fetch articles and full text (PMC/EPMC/Unpaywall), citations, MeSH terms.
Search scientific papers with structured experimental data from full-text studies
