pubmed-mcp-server

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses the critical behavioral constraint that the tool only resolves articles indexed in PubMed Central. No contradictions with annotations.

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?

Three sentences: purpose, constraint, alternative. No redundant or filler content. Front-loaded with core action.

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 2-parameter conversion tool with output schema present, the description fully covers purpose, constraints, and edge cases. No missing information.

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 covers 100% of parameters with descriptions. The description adds concrete format examples (DOIs: '10.1093/nar/gks1195', PMIDs: '23193287', PMCIDs: 'PMC3531190'), which help the agent format inputs correctly.

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 'Convert between article identifiers (DOI, PMID, PMCID)' with a specific verb and resource. It distinguishes from sibling tools by noting the PMC limitation and suggesting an alternative for non-PMC articles.

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 clear when-to-use and when-not-to-use guidance: 'Accepts up to 50 IDs of a single type per request' and for articles not in PMC, 'use pubmed_search_articles instead.' This explicitly directs the agent to the correct tool.

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

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

Discloses key behavioral traits beyond annotations: the scope of sources, default source behavior, pagination via cursorMark, sort field caveats for preprints, and result type options. This adds significant context not captured in the readOnlyHint and openWorldHint annotations.

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 well-structured, delivering critical information in a single focused paragraph. Every sentence adds value, and key points (purpose, usage, defaults, special considerations) are 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 complexity of the tool (multiple sources, pagination, sort constraints, result types) and the presence of an output schema, the description covers all essential aspects. It explains pagination, source filtering, sort caveats, and default behaviors, making it sufficient for an agent to invoke 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?

Schema coverage is 100% with good parameter descriptions, so baseline is 3. The tool description provides minor additional context (e.g., explaining default sources and sort limitations) but does not significantly enhance meaning beyond what the schema already provides.

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 Europe PMC, a broad biomedical corpus, and specifies the types of content covered (preprints, patents, Agricola, etc.). It distinguishes itself from sibling tools like pubmed_search_articles by emphasizing broader coverage beyond PubMed.

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?

Explicitly says when to use this tool ('Use when additional coverage is needed') and what typical recovery is. It also notes default sources and how to include additional sources, providing clear guidance on alternatives.

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

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

Annotations already mark readOnlyHint and openWorldHint true, so the description correctly aligns. It adds value by listing the returned data types (abstract, authors, journal, MeSH terms), which informs the agent about the scope of results without contradicting the annotations.

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 two sentences: the first states the core action, the second lists contents. It is front-loaded and concise, but given 10 siblings, a more structured breakdown (e.g., bullet points or explicit differentiation) could improve scanning for agents.

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 description is adequate for a tool with an output schema and annotations, but for an external API (openWorldHint), it omits constraints like max 200 IDs, reliance on prior search, or any rate limits. While the schema handles parameter details, external context is missing for a fully 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?

With 100% schema description coverage, the schema already fully explains the three parameters. The description only mentions 'PubMed IDs' and 'MeSH terms' broadly, which overlaps with the schema but does not add new semantic meaning or usage nuances beyond the structured definitions.

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 'Fetch' and resource 'full article metadata by PubMed IDs', and lists specific content like abstract, authors, journal, MeSH terms. This differentiates it from siblings such as pubmed_search_articles (search returns IDs) and pubmed_fetch_fulltext (full text), establishing a distinct 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?

The description implies usage when PubMed IDs are available and detailed metadata is needed, but lacks explicit when-to-use, when-not-to-use, or alternative guidance. Given 9 siblings, the description does not help the agent distinguish between fetch_articles and fetch_fulltext or search, leaving selection ambiguous.

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

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

Discloses fallback chain (PMC -> Europe PMC -> Unpaywall) and output formats (JATS, HTML-as-Markdown, PDF-as-text). Adds configuration requirement (UNPAYWALL_EMAIL) beyond the readOnlyHint and openWorldHint annotations. No 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?

Approximately 150 words, well-paragraphed, with a clear lead sentence. Could be slightly more concise by removing redundancy in parameter descriptions, but overall 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?

Covers fallback layers, parameter constraints, and output types. With an output schema present, return values are adequately handled. Minor gap: no mention of error handling or rate limits, but not essential for basic usage.

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 baseline is 3. The description adds meaningful context for each parameter (e.g., DOI resolution via ID Converter, PMC ID format with optional prefix), going beyond the schema's basic 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 starts with a specific verb+resource: 'Fetch full-text articles from PubMed Central with structured sections and references.' It clearly distinguishes from siblings like pubmed_fetch_articles (metadata) by focusing on full-text and multiple fallback layers.

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?

Explicitly states 'Provide exactly one of pmcids, pmids, or dois' and describes fallback behavior for each case. Provides clear context on when to use each parameter, though does not explicitly contrast with sibling tools.

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

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

The description adds valuable behavioral context beyond the readOnlyHint and openWorldHint annotations, disclosing the primary data source (NCBI ELink) and fallback sources (Europe PMC, OpenAlex). This informs the agent about reliability and potential latency.

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 two sentences: first covers purpose and options, second covers reliability. No redundant information, 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 and 100% parameter coverage, the description sufficiently covers what the tool does and its data sourcing behavior. No missing critical 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?

All four parameters already have descriptions in the input schema (100% coverage). The tool description largely repeats the relationship type explanations without adding new semantic meaning. The fallback information is not parameter-specific.

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 finds articles related to a source article, listing three specific relationship types (similar, cited_by, references). This distinguishes it from sibling tools like pubmed_search_articles which search broadly.

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 the fallback behavior when NCBI is unavailable and outlines the three relationship types. However, it does not explicitly state when to use this tool vs alternatives, nor does it provide exclusion criteria.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds value by specifying the exact styles and default behavior, but does not elaborate on potential error handling or rate limits.

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?

Two concise sentences that front-load the purpose, with no wasted words. Every sentence is necessary and clear.

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 an output schema present, return values need not be explained. The description covers the core functionality and constraints, though it could briefly mention that multiple PMIDs are accepted.

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 fully documents both parameters. The description reiterates that format can be a string or array, which adds no new 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 returns formatted citations for PubMed articles, listing specific styles. It distinguishes itself from sibling tools like pubmed_fetch_articles and pubmed_lookup_citation, 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 when formatted citations are needed and mentions the ability to pass single or multiple styles, but it does not provide explicit when-to-use or when-not-to-use guidance compared to alternative tools.

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

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

Beyond annotations (readOnlyHint, openWorldHint), description reveals it uses ECitMatch with primary keys on journal+volume+page, explains deterministic nature, and guarantees no match for certain inputs. No contradiction with annotations.

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?

Two sentences pack purpose, use case, reliability, constraints, and best practices. Every sentence adds value; no fluff.

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 one parameter (citations array) and existing output schema, the description fully explains matching logic, constraints, and reliability. No 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 coverage is 100%, but description adds context about minimum required fields (journal or year) and explains ECitMatch primary keys, which enhances understanding. Slightly above baseline 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?

Description clearly states the tool looks up PubMed IDs from partial bibliographic citations, specifies it's for structured references, and distinguishes from free-text search by noting deterministic matching. This differentiates it from sibling tools like pubmed_search_articles.

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?

Explicitly states when to use (having a reference with journal/year/volume/page/author) and warns against author-only or volume-only inputs. It also recommends more fields for better accuracy, providing clear guidance on optimal usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, confirming safe read behavior and that results may vary. The description adds value by specifying the output structure (scope notes, tree numbers, entry terms) but does not disclose any additional behavioral traits like pagination, error handling, or performance.

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, well-structured sentence that front-loads the core action ('Search and explore...') and efficiently lists key return elements. Every part serves a purpose with no 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?

For a tool with 3 well-documented parameters, a readOnlyHint annotation, and an output schema that defines the return structure, the description is relatively complete. It mentions the primary return fields, though it could optionally note that results might be empty or that input is case-insensitive.

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 clear descriptions for all parameters. The description does not add further semantic value beyond listing returned fields, so it meets the baseline expectations.

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 and explores the MeSH controlled vocabulary, and explicitly lists the returned data (descriptor records, tree numbers, scope notes, entry terms). This distinguishes it from sibling tools like pubmed_search_articles (article search) and pubmed_lookup_citation (citation lookup).

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 does not mention when not to use it or suggest alternative tools for similar tasks, such as when to use pubmed_search_articles for keyword-based article search instead.

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

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

Annotations (readOnlyHint, openWorldHint) already indicate safe, open-ended queries. Description adds value by specifying return of 'PMIDs and optional brief summaries' and mention of pagination. Does not contradict annotations. Could further detail rate limits or result format.

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?

Two efficient sentences front-loaded with primary function. Every word adds value; no redundant phrases. Ideal 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?

With 14 parameters, nested objects, and output schema present, the description covers key features (filters, pagination, summaries). Could include result size limit or output type details but is not deficient.

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 detailed parameter descriptions. Description summarizes filters and pagination but does not add new meaning beyond 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?

States 'Search PubMed with full query syntax' clearly identifying action and resource. Distinguishes from siblings like pubmed_fetch_articles (fetching) and pubmed_convert_ids (conversion) by specifying search with filters and pagination.

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?

Describes capabilities but does not explicitly guide when to use this tool vs. alternatives like pubmed_fetch_articles for full text or pubmed_lookup_citation for specific citations. Usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds context that it connects to 'NCBI' (aligning with openWorldHint), but does not disclose additional behavioral traits like what happens when no corrections exist or how many suggestions are returned.

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?

Two sentences with zero waste: first sentence defines the action and return value, second provides usage context. Appropriately front-loaded and sized for the tool's simplicity.

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 one parameter, simple structure, and an output schema exists, the description provides sufficient context. It could be improved by noting this is specifically for PubMed queries, but the tool name makes this clear.

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 100% schema description coverage, the schema already fully documents the 'query' parameter. The description does not add supplementary semantics, examples, or format constraints beyond what the schema provides, warranting the baseline score.

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 the specific action ('Spell-check a query'), the external resource ('NCBI's suggested correction'), and distinguishes clearly from sibling tools which focus on fetching articles, converting IDs, or formatting citations rather than query validation.

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?

Provides clear context on when to use ('Useful for refining search queries'), indicating it should be used for query validation before searching. However, it does not explicitly mention when NOT to use it or name specific sibling alternatives like pubmed_search_articles.

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