The PubMed MCP Server provides comprehensive tools for searching, retrieving, analyzing, and exporting information from PubMed via the Model Context Protocol (MCP).
Key capabilities include:
Advanced searching using complex criteria (keywords, date ranges, article types) and logical operators (AND, OR, NOT) across specific fields
Retrieving detailed article information including abstracts, metadata, and citation metrics by PMID
Finding related articles for a given PMID
Author-specific searches with co-author information
Journal-specific searches with journal metrics and notable articles
MeSH term exploration for precise medical subject searching
Publication trend analysis over time for research topics
Comparing multiple articles side by side based on various fields
Identifying trending medical topics based on recent publications
Exporting citations in multiple formats (BibTeX, APA, MLA, Chicago, Vancouver, EndNote, RIS)
Customizing results by controlling quantity and sort order
Provides containerization support with built-in Docker integration, enabling easy deployment and consistent runtime environment through provided Dockerfile and docker-compose configurations.
Used for configuration management, allowing users to set up required NCBI API credentials and optional settings like cache parameters and rate limits through environment variables.
Integrates with GitHub for issue tracking, documentation hosting via wiki, and community discussions, providing support channels for users of the MCP server.
Provides advanced PubMed literature search capabilities with complex filters, citation formatting in multiple formats, article details retrieval, author search, related article discovery, MeSH term exploration, journal analysis, and research trend analysis.
Utilized for data validation and modeling within the MCP server, enabling structured handling of PubMed data and tool requests.
Built on Python with specific version requirements (3.8+), leveraging Python's ecosystem for the MCP server implementation.
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., "@PubMed MCP Server search for recent articles about AI in cancer diagnosis from the last 2 years"
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 comprehensive Model Context Protocol (MCP) server for PubMed literature search and management. This server provides advanced search capabilities, citation formatting, and research analysis tools through the MCP protocol.
Advanced PubMed Search: Search with complex filters including date ranges, article types, authors, journals, and MeSH terms
Article Details: Retrieve detailed information for specific PMIDs including abstracts, authors, and metadata
Citation Export: Export citations in multiple formats (BibTeX, APA, MLA, Chicago, Vancouver, EndNote, RIS)
Author Search: Find articles by specific authors with co-author information
Related Articles: Discover articles related to a specific PMID
MeSH Term Search: Search and explore Medical Subject Headings
Journal Analysis: Get metrics and recent articles from specific journals
Research Trends: Analyze publication trends over time
Article Comparison: Compare multiple articles side by side
Caching: Built-in caching for improved performance
Rate Limiting: Respectful API usage with configurable rate limits
Related MCP server: NIH RePORTER MCP
Python 3.8 or higher
NCBI API key (free registration required)
Valid email address for NCBI API identification
Clone the repository:
git clone https://github.com/your-org/pubmed-mcp.git
cd pubmed-mcpInstall dependencies:
pip install -r requirements.txtSet up environment variables:
cp env.example .env
# Edit .env with your NCBI API key and emailRun the server:
python -m src.mainFor development with additional tools:
make install-devOr manually:
pip install -r requirements.txt
pip install -e .
pip install black isort mypy flake8Create a .env file in the project root with the following variables:
# Required
PUBMED_API_KEY=your_ncbi_api_key_here
PUBMED_EMAIL=your.email@example.com
# Optional
CACHE_TTL=300
CACHE_MAX_SIZE=1000
RATE_LIMIT=3.0
LOG_LEVEL=infoVisit NCBI Account Settings
Sign in or create an account
Navigate to "API Key Management"
Create a new API key
Copy the key to your .env file
The server provides the following MCP tools:
search_pubmedSearch PubMed with advanced filtering options.
{
"query": "machine learning healthcare",
"max_results": 20,
"date_range": "5y",
"article_types": ["Journal Article", "Review"],
"has_abstract": true
}get_article_detailsGet detailed information for specific PMIDs.
{
"pmids": ["12345678", "87654321"],
"include_abstracts": true,
"include_citations": false
}search_by_authorSearch for articles by a specific author.
{
"author_name": "Smith J",
"max_results": 10,
"include_coauthors": true
}export_citationsExport citations in various formats.
{
"pmids": ["12345678"],
"format": "bibtex",
"include_abstracts": false
}find_related_articlesFind articles related to a specific PMID.
{
"pmid": "12345678",
"max_results": 10
}search_mesh_termsSearch using MeSH terms.
{
"term": "Machine Learning",
"max_results": 20
}analyze_research_trendsAnalyze publication trends over time.
{
"topic": "artificial intelligence",
"years_back": 5,
"include_subtopics": false
}import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
server_params = StdioServerParameters(
command="python",
args=["-m", "src.main"]
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
# Initialize the session
await session.initialize()
# Search PubMed
result = await session.call_tool(
"search_pubmed",
{
"query": "COVID-19 vaccines",
"max_results": 5,
"date_range": "1y"
}
)
print(result.content[0].text)
if __name__ == "__main__":
asyncio.run(main())# Run all tests
make test
# Run with coverage
make test-coverage
# Run specific test types
python run_tests.py unit
python run_tests.py integration
python run_tests.py coverage# Format code
make format
# Run linting
make lint
# Type checking
mypy src/pubmed-mcp/
├── src/
│ ├── __init__.py
│ ├── main.py # Entry point
│ ├── server.py # MCP server implementation
│ ├── models.py # Pydantic models
│ ├── pubmed_client.py # PubMed API client
│ ├── tool_handler.py # Tool request handlers
│ ├── citation_formatter.py # Citation formatting
│ ├── tools.py # Tool definitions
│ └── utils.py # Utility functions
├── tests/ # Test suite
├── requirements.txt # Dependencies
├── setup.py # Package setup
├── pyproject.toml # Modern Python config
├── Makefile # Development commands
├── Dockerfile # Container setup
└── README.md # This file# Build Docker image
make docker-build
# Run with environment variables
make docker-run PUBMED_API_KEY=your_key PUBMED_EMAIL=your_emailversion: '3.8'
services:
pubmed-mcp:
build: .
environment:
- PUBMED_API_KEY=your_key
- PUBMED_EMAIL=your_email
- LOG_LEVEL=info
volumes:
- ./data:/app/dataquery: Search query using PubMed syntax
max_results: Maximum number of results (1-200)
sort_order: Sort order (relevance, pub_date, author, journal, title)
date_from/date_to: Date range filters
date_range: Predefined ranges (1y, 5y, 10y, all)
article_types: Filter by publication types
authors: Filter by author names
journals: Filter by journal names
mesh_terms: Filter by MeSH terms
language: Language filter (e.g., 'eng', 'fre')
has_abstract: Only articles with abstracts
has_full_text: Only articles with full text
humans_only: Only human studies
bibtex: BibTeX format
apa: APA style
mla: MLA style
chicago: Chicago style
vancouver: Vancouver style
endnote: EndNote format
ris: RIS format
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request
Follow PEP 8 style guidelines
Add type hints to all functions
Write comprehensive tests
Update documentation for new features
Use conventional commit messages
This project is licensed under the MIT License - see the LICENSE file for details.
Issues: GitHub Issues
Documentation: Project Wiki
Discussions: GitHub Discussions
NCBI E-utilities for PubMed API access
Model Context Protocol for the MCP specification
Anthropic for MCP development and support
See CHANGELOG.md for a detailed history of changes.
Note: This server requires a valid NCBI API key and follows NCBI's usage guidelines. Please be respectful of API rate limits and terms of service.
Perform complex PubMed searches with multiple criteria
| Name | Required | Description | Default |
|---|---|---|---|
| search_terms | Yes | Complex search criteria with fields and operators | |
| filters | No | Additional filters | |
| max_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It doesn't disclose whether this is a read-only operation, potential rate limits, authentication needs, or what the output looks like (e.g., result format, pagination). 'Perform complex searches' implies a query operation but lacks critical details for safe and effective use.
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 front-loads the core purpose without unnecessary elaboration. Every word contributes to understanding the tool's function, making it appropriately concise for a search operation.
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 tool with 3 parameters, nested objects, no output schema, and no annotations, the description is inadequate. It doesn't address behavioral aspects (e.g., safety, limits), output expectations, or differentiation from siblings, leaving significant gaps for an AI agent to navigate this complex search functionality.
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 67%, with parameters like 'search_terms' and 'filters' having descriptions that match the tool's purpose. The description adds marginal value by hinting at 'multiple criteria', but doesn't elaborate beyond what the schema provides (e.g., explaining how operators work in practice). Baseline 3 is appropriate given moderate schema coverage.
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 ('perform complex PubMed searches') and resource ('PubMed'), distinguishing it from simpler search tools. However, it doesn't explicitly differentiate from sibling tools like 'search_pubmed' or 'search_by_author', which would require more specific language about the 'complex' nature with 'multiple criteria'.
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 provides no guidance on when to use this tool versus alternatives like 'search_pubmed' or 'search_by_author'. It mentions 'complex searches with multiple criteria' but doesn't specify thresholds or scenarios where this tool is preferred over simpler siblings, leaving the agent to guess based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze publication trends for a research topic over time
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Research topic to analyze | |
| years_back | No | Number of years to analyze | |
| include_subtopics | No | Include analysis of related subtopics |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It mentions analyzing trends over time but doesn't describe what the analysis includes (e.g., publication counts, citation trends, visualizations), how results are returned, data sources, rate limits, or authentication requirements. For a tool with 3 parameters and no output schema, this is inadequate.
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 just one sentence with zero wasted words. It front-loads the core functionality and uses efficient language. Every word earns its place by communicating the essential purpose without unnecessary elaboration.
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 (analyzing trends over time with subtopic options), lack of annotations, and absence of an output schema, the description is insufficiently complete. It doesn't explain what kind of analysis is performed, what format results take, data sources, limitations, or how this differs from similar tools. The single sentence leaves too many operational questions unanswered.
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 fully documents all three parameters. The description adds no additional parameter semantics beyond what's in the schema - it doesn't explain how 'topic' should be formatted, what constitutes 'related subtopics', or how the time range affects analysis. The baseline score of 3 reflects adequate but unenhanced 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 tool's purpose as analyzing publication trends for a research topic over time, specifying both the action (analyze) and resource (publication trends). It distinguishes from siblings like 'get_trending_topics' (which likely shows current trends) and 'compare_articles' (which compares specific articles), but doesn't explicitly differentiate from all alternatives.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention when this analysis tool is preferable to 'get_trending_topics' for trend discovery or 'advanced_search' for detailed filtering. There's no context about prerequisites, limitations, or appropriate use cases beyond the basic functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare multiple articles side by side
| Name | Required | Description | Default |
|---|---|---|---|
| pmids | Yes | List of PMIDs to compare (2-5 articles) | |
| comparison_fields | No | Fields to compare |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It implies a read-only comparison operation but doesn't disclose output format, pagination, rate limits, authentication needs, or what 'side by side' means structurally (e.g., table, summary). This leaves significant gaps for agent understanding.
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 zero wasted words. It's appropriately sized for the tool's complexity and front-loaded with the core action, making it easy to parse quickly.
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 is incomplete for a tool with 2 parameters and comparison functionality. It lacks details on return values, error handling, or practical use cases, leaving the agent under-informed about how to effectively invoke and interpret results.
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%, with clear parameter documentation in the schema itself. The description adds no additional meaning about parameters beyond implying multi-article comparison, so it meets the baseline of 3 where the schema does the heavy lifting without compensating value.
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 'Compare multiple articles side by side' clearly states the verb (compare) and resource (articles), specifying the multi-article scope. However, it doesn't distinguish this from potential sibling tools like 'find_related_articles' or 'analyze_research_trends' that might also involve article comparison, missing explicit differentiation.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing PMIDs), exclusions, or how it differs from siblings like 'get_article_details' for single articles or 'analyze_research_trends' for broader analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export article citations in various formats
| Name | Required | Description | Default |
|---|---|---|---|
| pmids | Yes | List of PubMed IDs to export | |
| format | No | Citation format | bibtex |
| include_abstracts | No | Include abstracts in citations |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what the tool does but lacks critical behavioral details: whether this is a read-only operation, if it requires authentication, rate limits, what the output looks like (e.g., file download or text), or error handling. For a tool with no annotations, this is a significant 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, efficient sentence that front-loads the core purpose ('Export article citations') and adds essential context ('in various formats'). There is zero waste or redundancy, making it highly concise and 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?
Given the tool's complexity (export functionality with 3 parameters) and lack of annotations and output schema, the description is incomplete. It doesn't address behavioral aspects like output format, permissions, or error handling, which are crucial for an export tool. The schema covers parameters well, but overall context is insufficient.
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 fully documents all three parameters (pmids, format, include_abstracts). The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain format differences or pmid validation). Baseline 3 is appropriate when the schema does the heavy lifting.
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 with a specific verb ('Export') and resource ('article citations'), and specifies the output domain ('various formats'). It doesn't explicitly distinguish from sibling tools like 'get_article_details' or 'search_pubmed', but the export focus is clear. No tautology or misleading elements are present.
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 provides no guidance on when to use this tool versus alternatives. With sibling tools like 'get_article_details' and 'search_pubmed' that might retrieve citation data, there's no indication of when export is preferred (e.g., for formatted outputs vs raw data). Usage is implied by the name but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information for specific articles by PMID
| Name | Required | Description | Default |
|---|---|---|---|
| pmids | Yes | List of PubMed IDs | |
| include_abstracts | No | Include abstracts in response | |
| include_citations | No | Include citation count and metrics |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Get' implies a read-only operation, it doesn't specify whether this requires authentication, has rate limits, returns structured data, or handles errors. For a tool with 3 parameters and no annotation coverage, this leaves significant behavioral questions unanswered.
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 immediately conveys the core functionality. Every word earns its place - 'Get detailed information' establishes the action, 'for specific articles' defines scope, and 'by PMID' specifies the key identifier. No wasted words or unnecessary elaboration.
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 tool with 3 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what 'detailed information' includes beyond the parameter hints, doesn't describe the response format, and provides no context about PubMed integration or data freshness. The combination of missing behavioral context and output uncertainty creates significant 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?
Schema description coverage is 100%, so all parameters are documented in the schema. The description adds no additional parameter information beyond what's in the schema - it doesn't explain PMID format, abstract inclusion implications, or citation metrics details. The baseline score of 3 reflects adequate but minimal value addition over the comprehensive 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 verb 'Get' and resource 'detailed information for specific articles by PMID', making the purpose immediately understandable. It distinguishes from siblings like 'search_by_author' or 'advanced_search' by focusing on retrieval of specific articles rather than searching or analysis. However, it doesn't explicitly differentiate from 'compare_articles' or 'find_related_articles' which might also work with PMIDs.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over 'search_pubmed' for article retrieval, or when 'compare_articles' might be more appropriate for multi-article analysis. There's no discussion of prerequisites, limitations, or optimal use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metrics and information about a specific journal
| Name | Required | Description | Default |
|---|---|---|---|
| journal_name | Yes | Journal name or abbreviation | |
| include_recent_articles | No | Include recent notable articles |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves metrics and information, implying a read-only operation, but lacks details on permissions, rate limits, error handling, or what specific metrics are returned. This is inadequate for a tool with no annotation coverage.
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 directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it highly concise and well-structured.
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 is incomplete. It doesn't explain what metrics are returned, how data is formatted, or any behavioral traits. For a tool that retrieves information, this leaves significant gaps in understanding its functionality and 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 100% description coverage, clearly documenting both parameters. The description adds no additional meaning beyond what the schema provides, such as examples or context for 'journal_name' or 'include_recent_articles'. Baseline score of 3 is appropriate since the schema does the heavy lifting.
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 ('Get') and resource ('metrics and information about a specific journal'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'search_by_journal' or 'get_article_details', which could provide overlapping functionality, so it doesn't reach the highest score.
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 provides no guidance on when to use this tool versus alternatives. With siblings like 'search_by_journal' and 'get_article_details' available, there's no indication of scenarios where this tool is preferred or excluded, leaving usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get trending medical topics and research areas
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Medical category (e.g., 'cardiology', 'oncology', 'neurology') | |
| days | No | Number of days to analyze for trends |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'gets' trending topics, implying a read-only operation, but doesn't mention any behavioral traits such as rate limits, authentication needs, data freshness, or what the output format might be. This leaves significant gaps for an agent to understand how to interact with it effectively.
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 directly states the tool's purpose without any unnecessary words. It's front-loaded and wastes no space, making it easy for an agent to parse quickly.
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 complexity of fetching trending data, lack of annotations, and no output schema, the description is incomplete. It doesn't explain what 'trending' means (e.g., based on publication volume, citations, or social media), the scope of data sources, or the structure of returned results. This leaves the agent with insufficient context to use the tool effectively.
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 100% description coverage, clearly documenting both parameters ('category' and 'days') with details like allowed values and defaults. The description adds no additional meaning beyond what the schema provides, such as explaining how 'category' affects results or what 'trending' entails. With high schema coverage, 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 clearly states the tool's purpose with a specific verb ('Get') and resource ('trending medical topics and research areas'), making it easy to understand what it does. However, it doesn't distinguish itself from potential siblings like 'analyze_research_trends' or 'search_mesh_terms', which might have overlapping functionality in medical trend analysis.
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 provides no guidance on when to use this tool versus alternatives. With siblings like 'analyze_research_trends' and 'search_mesh_terms' that might handle similar medical trend data, there's no indication of context, prerequisites, or exclusions to help an agent choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for articles by a specific author
| Name | Required | Description | Default |
|---|---|---|---|
| author_name | Yes | Author name to search for | |
| max_results | No | Maximum number of results | |
| include_coauthors | No | Include co-author information |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action ('Search for articles') without adding context such as permissions needed, rate limits, pagination behavior, or what the search returns (e.g., list format, error handling). For a search tool with zero annotation coverage, this is a significant gap in 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, efficient sentence that directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it easy for an agent to parse quickly. Every part of the sentence earns its place by conveying essential information.
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 (a search function with 3 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain return values, error conditions, or behavioral traits, leaving gaps that could hinder an agent's ability to use the tool effectively. The description should provide more context to compensate for the missing structured data.
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%, meaning the input schema fully documents all parameters (author_name, max_results, include_coauthors). The description adds no additional meaning beyond what the schema provides, such as examples or usage tips. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
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 as 'Search for articles by a specific author,' which includes a specific verb ('Search') and resource ('articles') with a clear filter criterion ('by a specific author'). It distinguishes from general search tools but doesn't explicitly differentiate from sibling tools like 'search_by_journal' or 'advanced_search,' which might also involve article searches with different filters.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'advanced_search' or 'search_by_journal,' nor does it specify contexts, prerequisites, or exclusions for usage. This leaves the agent without explicit direction for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search articles from a specific journal
| Name | Required | Description | Default |
|---|---|---|---|
| journal_name | Yes | Journal name or abbreviation | |
| max_results | No | Maximum number of results | |
| date_from | No | Start date (YYYY/MM/DD) | |
| date_to | No | End date (YYYY/MM/DD) |
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 states the action ('Search') but doesn't mention whether this is a read-only operation, potential rate limits, authentication requirements, or what the output format might be. For a search tool with zero annotation coverage, this is a significant 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, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, earning a perfect score for 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 complexity of a search operation with 4 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what kind of results to expect, how they're formatted, or any behavioral constraints. The agent would need to guess about the tool's behavior beyond the basic purpose.
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 all four parameters thoroughly. The description adds no additional parameter information beyond what's in the schema, but since the schema does the heavy lifting, 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 clearly states the verb ('Search') and resource ('articles from a specific journal'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'search_by_author' or 'advanced_search', which limits its score to 4 rather than 5.
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 provides no guidance on when to use this tool versus alternatives like 'search_by_author' or 'advanced_search'. It lacks context about use cases, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and explore MeSH (Medical Subject Headings) terms
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | MeSH term to search for | |
| max_results | No | Maximum number of results |
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 mentions 'search and explore' but doesn't specify whether this is a read-only operation, if it requires authentication, what the response format looks like, or any rate limits. For a search tool with zero annotation coverage, this is a significant gap in 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, efficient sentence with zero wasted words. It's appropriately sized and front-loaded, clearly stating the core functionality without unnecessary elaboration.
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 moderate complexity (search operation with 2 parameters), 100% schema coverage, but no annotations and no output schema, the description is minimally adequate. It states what the tool does but lacks details on behavior, output, or differentiation from siblings, leaving gaps for the agent to navigate.
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 fully documents both parameters ('term' and 'max_results'). The description adds no additional meaning beyond what's in the schema, such as explaining search semantics or result formatting. Baseline 3 is appropriate when the schema does the heavy lifting.
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 explore') and resource ('MeSH terms'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'search_pubmed' or 'advanced_search', which might also involve searching medical content, so it doesn't reach the highest score.
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 provides no guidance on when to use this tool versus alternatives like 'search_pubmed' or 'advanced_search'. It lacks context about specific use cases, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search PubMed for articles with advanced filtering options
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query using PubMed syntax | |
| max_results | No | Maximum number of results to return | |
| sort_order | No | Sort order for results | relevance |
| date_from | No | Start date (YYYY/MM/DD, YYYY/MM, or YYYY) | |
| date_to | No | End date (YYYY/MM/DD, YYYY/MM, or YYYY) | |
| date_range | No | Predefined date range | |
| article_types | No | Filter by article types | |
| authors | No | Filter by author names | |
| journals | No | Filter by journal names | |
| mesh_terms | No | Filter by MeSH terms | |
| language | No | Language filter (e.g., 'eng', 'fre', 'ger') | |
| has_abstract | No | Only include articles with abstracts | |
| has_full_text | No | Only include articles with full text available | |
| humans_only | No | Only include human studies |
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 but offers minimal information. It mentions 'advanced filtering options' but doesn't describe critical behaviors such as rate limits, authentication needs, pagination, error handling, or what the output looks like (e.g., article metadata). This is inadequate for a tool with 14 parameters and no 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, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it easy for an agent to parse quickly.
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 complexity (14 parameters, no annotations, no output schema, multiple sibling tools), the description is incomplete. It doesn't explain the tool's behavior, output format, or usage context, leaving significant gaps for an agent to understand how to invoke it effectively compared to alternatives.
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 schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional semantic context beyond implying filtering capabilities, which is already covered by the schema. This meets the baseline of 3 when the schema does the heavy lifting.
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 as 'Search PubMed for articles with advanced filtering options,' which specifies the verb (search), resource (PubMed articles), and scope (advanced filtering). However, it doesn't explicitly differentiate from sibling tools like 'search_by_author' or 'search_by_journal,' which are more specific variants.
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 provides no guidance on when to use this tool versus alternatives like 'advanced_search' or 'search_by_author.' It lacks context about use cases, prerequisites, or exclusions, leaving the agent to infer usage from the tool name and parameters alone.
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.
v1.0.0advanced_searchanalyze_research_trendscompare_articlesexport_citationsfind_related_articlesget_article_detailsget_journal_metricsget_trending_topicssearch_by_authorsearch_by_journalsearch_mesh_termssearch_pubmedScored across 12 tools
Most tools have clearly distinct purposes, such as get_article_details for specific articles versus search_pubmed for general queries. However, advanced_search and search_pubmed could potentially overlap in functionality, as both involve searching PubMed with filtering options, which might cause minor confusion for an agent.
The naming follows a consistent verb_noun pattern throughout, like search_by_author and get_journal_metrics, with clear and descriptive terms. There are minor deviations, such as advanced_search using an adjective instead of a verb, but overall the pattern is predictable and readable.
With 12 tools, this server is well-scoped for a PubMed interface, covering a range of functions from basic searches to advanced analyses. Each tool appears to earn its place by addressing specific aspects of PubMed interaction, such as searching, analyzing trends, and exporting data.
The tool set provides comprehensive coverage for PubMed operations, including search, analysis, and export functionalities. Minor gaps might exist, such as the lack of tools for user-specific features like saving articles or managing alerts, but core workflows for research and article retrieval are well-covered.
Auditable MCP server for PubMed, Europe PMC, ClinicalTrials.gov, and bioRxiv/medRxiv queries
Search 36M+ PubMed biomedical articles and ClinicalTrials.gov studies.
Search biomedical papers, inspect publication records, and traverse citation or semantic graphs.
Search PubMed/Europe PMC, fetch articles and full text (PMC/EPMC/Unpaywall), citations, MeSH terms.