pubmed-mcp-server

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

The description discloses the read-only nature (consistent with readOnlyHint=true) and adds behavioral details: single ID type per request, limit of 50, and PMC-only coverage. 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?

The description is two sentences, front-loaded with the main purpose, and every sentence provides essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and full parameter documentation, the description covers input constraints, limitations, and alternatives, making it fully complete for a conversion tool.

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 coverage, the description adds valuable formatting examples for each ID type and explains that the PMC prefix is optional. For idType, it clarifies the necessity for unambiguous resolution, exceeding schema 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 'Convert between article identifiers (DOI, PMID, PMCID)', using a specific verb and resource. It distinguishes from sibling tools like pubmed_search_articles and pubmed_fetch_articles by focusing on identifier conversion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly limits usage to up to 50 IDs of a single type and notes the restriction to PubMed Central articles, directing users to pubmed_search_articles for non-PMC articles. This provides clear when-to-use and when-not-to-use guidance.

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 value by explaining that it returns the full untruncated abstract (beyond the truncated snippet from search), that it pairs with pubmed_europepmc_search, and that up to 25 records can be fetched per call. This provides useful behavioral context beyond 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 concise with only three sentences, each focused and front-loaded: first sentence states the core purpose, second explains the pairing with search, third covers edge cases and alternatives. No redundant 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 output schema exists (external), the description does not need to detail return values. It covers the essential contextual points: batch limit, pairing with search, and when this tool is the only option. Completeness is high, though some users might want confirmation of ordering or pagination, but these are not critical for a simple fetch tool.

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% as both parameters (source and epmcId) are described in the schema. The description adds semantic value by instructing to copy values from search hits, specifying that epmcId for MED records is the PMID, and explaining the behavior for PMC records (resolves to canonical MED record). This goes beyond raw schema 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 clearly states the action ('Fetch complete Europe PMC records') and the resource (records addressed by source+epmcId), specifying that it includes the full untruncated abstract. It distinguishes from siblings by explicitly naming pubmed_europepmc_search as the companion tool that returns truncated abstracts, making the purpose unambiguous.

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 explicit guidance on when to use this tool: after pubmed_europepmc_search when abstract is truncated, and for records lacking PMID/DOI (PPR, PAT, AGR) where pubmed_fetch_articles and pubmed_fetch_fulltext cannot be used. It also states the batch limit of 25 records per call, leaving no ambiguity about usage context.

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 that abstracts are returned as bounded abstractSnippet with abstractTruncated indicator, and directs to pubmed_europepmc_fetch for full abstract. Notes that P_PDATE_D sort is ignored for preprint-only sets. No contradictions with annotations (readOnlyHint and openWorldHint are consistent).

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 paragraph is well-organized, front-loaded with core purpose, and every sentence contributes essential information. 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?

Given the output schema existence and 100% schema coverage, the description provides complete guidance: sources, pagination, result types, abstract handling, and sorting quirks. Sufficient for effective use.

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?

Adds significant value beyond the input schema, including query field token examples with unquoted identifier rules, sort field limitations for preprints, and clear pagination guidance. All 6 parameters benefit from extra context.

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?

Clearly states it searches Europe PMC, a broad biomedical corpus, and lists covered sources (preprints, patents, Agricola, PubMed, PMC). Distinguishes itself from sibling tools like pubmed_search_articles by explicitly mentioning additional coverage for preprints and EPMC-only OA records.

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 ('when additional coverage is needed') and provides default sources, pagination via cursorMark, and how to include additional sources. Does not explicitly exclude sibling tools but provides enough context for agent decision-making.

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 context about the return structure (abstract, authors, etc.) beyond the annotations' readOnlyHint and openWorldHint. However, it does not disclose potential limitations like rate limits or pagination, which are not covered by 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: two sentences, front-loaded with the action and input, followed by output details. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a straightforward fetch tool with a full input schema and output schema, the description is adequate. It omits mention of the required parameter but that is clear from the schema. Overall, it provides sufficient context for an agent to understand the tool's role.

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 schema coverage at 100%, the baseline is 3. The description mentions return content (MeSH terms) that relates to the includeMesh parameter but does not add detail beyond the schema's own descriptions for pmids, includeMesh, and includeGrants.

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: fetching full article metadata by PubMed IDs. It lists specific content (abstract, authors, journal, MeSH terms), distinguishing it from sibling search tools like pubmed_search_articles or pubmed_europepmc_fetch.

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. It does not mention prerequisites, exclusions, or trade-offs compared to sibling tools such as pubmed_fetch_fulltext or pubmed_europepmc_fetch.

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 declare readOnlyHint and openWorldHint, and the description transparently discloses complex fallback behavior, truncation modes (truncate vs. outline), per-article budget, section filtering, and reference inclusion rules. 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?

The description is comprehensive but still well-structured: first sentence summarizes the core function, then fallback layers, then individual parameter guidance. It is slightly lengthy but every sentence adds value. Minor redundancy (e.g., 'Provide exactly one of' repeated) could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters, full schema coverage, annotations, and an output schema, the description covers all important aspects: fallback chains, truncation modes, budget constraints, section filtering, and reference inclusion. It is fully adequate for an agent to correctly invoke the tool.

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 baseline 3. The description adds significant context beyond the schema: fallback resolution for each ID type, Unpaywall layer conditions, truncation mode details, and budget interactions. This justifies a score above baseline.

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 fetches full-text articles from PubMed Central with structured sections and references, and details multiple fallback layers (Europe PMC, Unpaywall). It distinguishes from sibling tools like pubmed_fetch_articles by emphasizing structured JATS output and fallback behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to provide exactly one of pmcids, pmids, or dois, and explains when each is appropriate based on fallback logic. It mentions the Unpaywall requirement (UNPAYWALL_EMAIL) and provides guidance on truncation modes. It could be improved by contrasting with siblings like pubmed_fetch_articles for abstract-only use.

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 provide readOnlyHint and openWorldHint. The description adds valuable behavioral context by disclosing the fallback cascade (NCBI ELink -> Europe PMC -> OpenAlex), informing the agent about data source reliability and potential variability. No contradictions. Minor omission of failure modes or rate limits prevents a higher score.

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 two-sentence block with no wasted words. It front-loads the main purpose and then adds a concise note about fallback sources. Every sentence earns its place.

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 covers the core action, relationship types, and data source behavior. Since an output schema exists, details about return values are not needed. It lacks mention of pagination or prerequisites, but those are covered by schema annotations. Overall, it is sufficiently complete for a tool with rich structured metadata.

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 parameters are already well-documented. The description reinforces the 'relationship' parameter semantics by listing the three types, but adds minimal new meaning beyond what the schema provides. 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 finds articles related to a source article and enumerates three distinct relationship types (similar, cited_by, references). This specificity differentiates it from siblings like pubmed_search_articles or pubmed_fetch_articles, 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 provides clear context for when to use the tool (when you have a PMID and need related articles of a specific type). It does not explicitly exclude alternatives or provide when-not-to-use guidance, but the unique function and listed relationship types implicitly guide 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, making the tool's safe, read-only nature clear. The description adds the detail that citations are returned in multiple formats, which is consistent with annotations but does not provide additional behavioral context beyond them.

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 with the action and key details front-loaded. Every word earns its place, making it efficient and easy to parse.

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 low complexity (2 parameters), full schema coverage, presence of annotations, and an output schema, the description is sufficiently complete. It lists all supported formats and the parameter usage, leaving no obvious 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%, so both pmids and format are well-documented in the schema. The tool description restates the ability to pass a single format as a string or multiple as an array, adding marginal clarity but not significantly beyond the schema's explanation.

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'), the resource ('formatted citations for PubMed articles'), and the specific set of formats. It effectively distinguishes this tool from siblings like pubmed_fetch_articles, which retrieve raw article data.

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 how to pass formats but does not explicitly state when to use this tool versus alternatives like pubmed_fetch_articles. The intended use is implied but not directly contrasted with siblings.

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 reveals deterministic matching behavior, details primary keys (journal+volume+page), and explains accuracy dependence on field completeness. Annotations provide readOnlyHint and openWorldHint, and the description adds context without contradiction.

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 three sentences, front-loading the core action and purpose, with each sentence providing essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and full schema coverage, the description thoroughly covers input requirements, failure modes, and accuracy guidance, making it complete for this tool.

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 the description adds meaning by explaining the ECitMatch logic and providing examples (e.g., 'mann bj') and constraints that go beyond the schema 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 clearly states 'Look up PubMed IDs from partial bibliographic citations,' specifies the use case for structured references, and distinguishes from siblings like pubmed_search_articles by noting it is 'more reliable than free-text search for structured references.'

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 advises when to use ('when you have a reference... and need the PMID'), warns about minimal requirements ('at least journal or year'), and explains failure conditions ('author-only or volume-only inputs guarantee no match').

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 indicate readOnlyHint=true and openWorldHint=true, and the description adds value by detailing the return content (descriptor records, tree numbers, scope notes) and pagination via offset. No contradictions; the description enhances understanding beyond 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?

Two sentences, front-loaded with purpose, no wasted words. The structure efficiently conveys key 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 existence of an output schema and comprehensive annotations, the description covers all essential aspects: purpose, return data, and pagination. No gaps in 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 baseline is 3. The description does not add significant new meaning beyond what the schema already provides for parameters like query, offset, maxResults, and includeDetails.

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, specifying returned data like tree numbers, scope notes, and entry terms. It effectively differentiates from siblings (e.g., pubmed_search_articles for articles, not MeSH).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for MeSH lookups and mentions pagination behavior, but it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The context is clear but not exhaustive.

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 provide `readOnlyHint: true` and `openWorldHint: true`. The description adds behavioral details: dateRange requires both min and max, offset cap at 9998, summaryCount cap at 50, MeSH terms are AND'd, publicationTypes are OR'd, and pagination behavior with offset. 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?

The description is a single paragraph of three sentences, front-loaded with purpose and outputs, followed by filter details. No wasted words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (14 params, nested objects, output schema), the description covers query syntax, filters, date range behavior, pagination limits, and summary behavior. It mentions the output schema exists but does not detail return values (not required as output schema is provided). Slightly incomplete: does not state that default output is only PMIDs.

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%. The description adds value beyond the schema by explaining the dateRange activation condition (both min/max required), offset cap rationale, summaryCount guidance, and AND/OR logic for filters. It also references a sibling tool for extended summaries.

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 PubMed with full query syntax, filters, and date ranges. It specifies outputs: PMIDs and optional summaries. It distinguishes from siblings by mentioning `summaryCount` and directing users to `pubmed_fetch_articles` for more summaries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching and retrieving PMIDs/summaries, and mentions pagination and result caps. It hints at using `pubmed_fetch_articles` for more summaries, but does not explicitly state when to use this tool versus alternatives or provide exclusions.

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 provide readOnlyHint=true and openWorldHint=true, indicating safe behavior. The description adds that the tool returns a suggested correction, which is useful context but does not disclose any further behavioral details (e.g., whether it modifies anything).

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, front-loaded with the action and purpose. Every word is meaningful, with no fluff or repetition.

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 tool with one parameter and a likely straightforward output, the description is adequate. The presence of an output schema (not detailed) reduces the need to describe return values. Slightly more context on the correction format could improve it.

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% for the single parameter 'query', with description in the schema. The tool description does not add new semantics beyond what the schema provides, so 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 the verb ('spell-check'), resource ('query'), and outcome ('get NCBI's suggested correction'). It also indicates usefulness for refining search queries, distinguishing 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?

The description implies usage for refining search queries but does not explicitly state when to use or avoid this tool versus alternatives. No exclusions or context for when to choose this tool over siblings.

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