pubmed-mcp

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

With no annotations present the description carries the full burden, and it delivers: it discloses the credential requirement (UNPAYWALL_EMAIL or NCBI_EMAIL) and the degraded behavior without it (only PubMed Central links found), plus the 100-PMID ceiling. The semantic caveat about false negatives is exactly the kind of context an agent cannot infer from structured fields.

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?

Front-loads the classification outcome, then layers in mechanism, caveat, limit and prerequisite in four tight sentences. No filler and no repetition of the tool name.

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?

There is no output schema, so the description appropriately defines the return categories itself, along with the lookup mechanisms and environment prerequisites. An agent has everything needed to call it correctly 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 coverage is 0% for the single pmids parameter, so the description must compensate; it contributes the hard constraint of max 100 PMIDs per call, which the schema does not express. It stops short of specifying the PMID format (string vs numeric), leaving a minor gap.

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?

Uses a precise verb ('Classify each PMID') and enumerates the exact output taxonomy — open-access PDF, landing page only, no open access found, unchecked — so the tool's function is unmistakable. This clearly separates it from siblings like download_pdfs and pubmed_fetch, which retrieve rather than classify access status.

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?

Explains the meaning and limits of the result ('no_open_access_found' is not proof of inaccessibility) and states the operational cap of 100 PMIDs per call. It does not explicitly name when to prefer this over siblings such as search_with_access, but the usage context is clear.

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?

With no annotations present, the description carries the full burden and does a solid job: it discloses the 50-item cap, that paywalled content is skipped and never bypassed, the naming convention, folder resolution rules including the default, and that files are validated by the %PDF magic bytes with HTML login/bot-check pages rejected and reported as failures. It does not state rate limits or authentication requirements, which keeps it from a 5.

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?

Front-loaded with the core action and its limits, and the second paragraph is dense with operational detail rather than filler. The mid-paragraph 'folder:' label is slightly awkward but the text is otherwise tight and 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?

For a two-parameter tool with no annotations and no output schema, the description covers the critical unknowns: which papers are downloadable, where files land, how they are named, and how unverifiable files surface as failures. Missing return-value structure (e.g., counts or per-PMID status list) is a minor gap.

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 0%, so the description must compensate, and it does so well for 'folder': absolute path vs. a sub-folder name resolved under PUBMED_PDF_DIR with a stated default of ~/pubmed_pdfs. For 'pmids' it adds only the max-50 constraint and the PMID<id>.pdf output mapping, leaving the expected ID format implicit.

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 a specific verb and resource ('Download open-access PDFs for the given PMIDs') plus the output artifact ('as PMID<id>.pdf'), which clearly separates it from abstract/fetch siblings like fetch_abstracts and pubmed_fetch. It stops short of naming an alternative tool explicitly, so it lands at 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 conveys scope constraints that imply usage (open-access only, max 50 PMIDs, paywalled papers skipped rather than bypassed), which tells the agent this is not a general access tool. However, it never states when to prefer this over check_access or search_with_access, nor any prerequisite step for obtaining PMIDs, so guidance remains implicit.

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?

With no annotations provided, the description carries the full burden and does well: it declares the missing-field sentinel string, the `not_found` behavior for PMIDs NCBI omits, the presence of a retraction-notice flag, and an explicit instruction never to infer or complete missing text. It omits auth/rate-limit behavior and any failure modes, which keeps it short of a 5.

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?

Front-loaded with the action, then a compact enumeration of returned fields, then two behavioral rules. The field list is long but justified because no output schema exists. No wasted sentences.

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

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

With no output schema and no annotations, the description fully specifies the return shape, the sentinel for absent data, and the `not_found` channel, plus an anti-hallucination rule. That is everything an agent needs to consume the result 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?

One parameter at 0% schema description coverage, so the description must compensate. It does add real meaning — the input is a list of PMIDs and is capped at 200 — but says nothing about PMID formatting, duplicates, or empty-list behavior. Partial compensation only.

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 a specific verb and resource — fetching exact PubMed records via NCBI efetch for up to 200 PMIDs — so the agent knows exactly what it does. However, the sibling set (pubmed_fetch, pubmed_get, pubmed_batch_fetch) is highly overlapping, and the description never names or distinguishes itself from those 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?

No statement of when to use this tool versus pubmed_fetch, pubmed_get, or pubmed_batch_fetch, even though those siblings appear functionally similar. The only usable context is an implicit one: batch retrieval by PMID list. Nothing tells the agent when this is the wrong choice.

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?

With no annotations, the description carries the full burden and does substantial work: it discloses chunking into batch_size, the 1-200 cap, retstart pagination up to total_records, the fallback of querying the history count when total_records is omitted, and the per-record status/not_found reporting. It omits auth/API-key requirements and NCBI rate-limit behavior, which matter for large batches.

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?

Front-loaded one-line summary followed by organized mode, Args, and Returns sections; all content is relevant. Minor redundancy where the chunking/max-200 rule is stated in both the intro and the batch_size entry.

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 two-mode, six-parameter tool with no annotations and no output schema, the description covers modes, prerequisites, parameter meanings, and return shape, which is close to sufficient. Missing only operational caveats such as token expiry, rate limits, and error behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: every one of the six parameters is explained with meaning, defaults, and ranges (batch_size 1-200 default 200, retstart default 0, total_records fallback, webenv/query_key provenance). This is meaningfully richer than the bare 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?

States a specific verb+resource (batch fetch PubMed records) plus the differentiating scope: long PMID lists (>200) and Entrez History retrieval. An agent can distinguish it from pubmed_fetch/pubmed_get, which have no such batching framing.

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?

Gives clear mode-selection conditions: direct PMID batching when you have an arbitrary PMID list, versus Entrez History mode when webenv/query_key come from a prior pubmed_search(..., use_history=True). It stops short of explicitly stating when to prefer this over pubmed_fetch for small lists, so no true exclusion rule.

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?

No annotations are provided, so the description carries the full burden. It discloses that the data comes 'directly from NCBI EInfo' and is 'audit-grade,' which is useful provenance context, but it does not describe read-only safety, rate limits, or error behavior.

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 the return contents and followed by provenance. No filler, though slightly terse for a tool whose main value is a list of returned fields.

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 single-parameter, no-output-schema tool, the description covers what fields are returned and the parameter default, which is adequate. However, with no annotations and no output schema, it could say more about the read-only, non-destructive nature and the expected response shape.

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 0%, so the description must compensate for the single 'db' parameter. It explicitly identifies the parameter as an 'NCBI database' and states the default is 'pubmed', covering the only parameter's meaning.

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 a specific verb ('Get') and resource ('metadata, last update date, record count, and search field tags for an NCBI database'), making its purpose clear and distinct from search/fetch siblings. It doesn't explicitly contrast itself against those siblings, which keeps it from a 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 implies this is an informational/metadata tool by listing what it returns, but it gives no explicit when-to-use guidance, prerequisites, or conditions for choosing it over siblings like pubmed_search or pubmed_fetch. Usage is only implied.

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?

With no annotations, the description carries the full behavioral burden and does well: it discloses provenance guarantees ('every field comes strictly from the NCBI response'), no-inference policy for missing fields, and the concrete status values 'success' and 'not_found'. It omits auth requirements and rate-limit behavior, so it falls short of a 5.

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 short sentences, front-loaded with the core action and method, with the return-status detail following. No filler, though the two return-value sentences could be compressed into one.

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

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

With no output schema, the description appropriately explains the return contract (per-record status and provenance). For a single-parameter fetch tool this is nearly sufficient; the main gap is the absence of any routing guidance relative to the many similar sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter (pmids) at 0% schema description coverage, so the description must compensate. It implies exact-identifier lookup via 'exact PubMed records', which loosely conveys that pmids are precise identifiers, but it never states the format (bare PMID strings vs. prefixed), nor whether order is preserved or how many IDs are accepted.

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 a specific verb (fetch), resource (PubMed records), and method (NCBI efetch), and the word 'exact' signals the precise-lookup nature of the tool. However, it does not distinguish itself from siblings like pubmed_get or pubmed_batch_fetch, leaving the agent to infer the boundary.

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?

There is no explicit when-to-use or when-not-to-use guidance, and none of the closely related siblings (pubmed_get, pubmed_batch_fetch, fetch_abstracts) are named as alternatives. The intended usage (retrieve records by exact PMIDs) is only implied by the phrase 'exact PubMed records'.

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?

No annotations are supplied, so the description carries the full burden. It does disclose meaningful mode behavior – normalized returns a deterministic schema with structured missingness indicators, raw returns verbatim XML with a SHA-256 integrity hash – which is real added context. But it is silent on error/not-found behavior, auth or rate limits, and whether normalized output is lossy, leaving significant disclosure gaps for a no-annotation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The lead sentence is front-loaded and states purpose and payload in one breath, and the Args list is compact with no redundant prose. Slightly heavier than necessary but every line carries 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?

With no output schema, the description takes on return-value explanation and does so at a useful level (normalized schema vs raw XML + hash). Combined with the documented parameters, an agent has enough to call it correctly; only edge-case/error handling is unaddressed.

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 0%, so the description must compensate, and it does: it documents both parameters, gives the PMID format constraint (1-9 digits), and supplies the enum-like mode values 'normalized'/'raw' plus their semantics, which the schema itself lacks. Only minor gaps remain (e.g., what 'deterministic schema' concretely contains).

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 a specific verb and resource – 'Retrieve a single PubMed record by PMID' – and the singular scope contrasts implicitly with pubmed_batch_fetch. However, it never explicitly differentiates itself from close siblings like pubmed_fetch or search_pubmed, so an agent must infer which retrieval tool to pick.

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?

Usage is only implied: retrieve when you already hold a PMID. There is no explicit when-to-use, when-not-to-use, or named alternative among the many retrieval/search siblings, and no stated prerequisite that the caller must already have resolved an identifier.

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?

With no annotations, the description carries the full burden. It does disclose one meaningful behavior — use_history stores the search server-side and returns webenv & query_key — plus mentions query translation and audit provenance. But it never states that this is a non-mutating read, says nothing about NCBI E-utilities rate limits/API-key throttling, and does not describe the return payload.

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?

Effectively front-loaded: one summary sentence followed by a compact Args list, with no redundant prose. The opening sentence leans on opaque jargon ('reproducibility object', 'audit provenance') that consumes space without resolving into actionable meaning.

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 7-parameter tool with no annotations and no output schema, the description covers parameters well but leaves the agent guessing on return shape, pagination semantics, rate-limit behavior, and how this differs from sibling search_pubmed. Adequate to invoke, incomplete to invoke confidently in a crowded sibling set.

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 0% (titles only), so the description must compensate and largely does: it documents all seven parameters, including the 1-200 bound on max_results, that start maps to retstart, the allowed sort values, and that date_from/date_to are publication-year bounds. It stops short of clarifying how start/max_results should be combined for paging or what webenv/query_key are consumed by.

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 a specific verb and resource (search PubMed / NCBI esearch) and hints at distinctive features (query translation, audit provenance), so the agent knows this is an Entrez-backed PubMed search. However, it does not distinguish itself from the near-identically named sibling 'search_pubmed', which an agent could easily pick instead.

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 when-to-use guidance, no when-not-to-use, and no reference to alternatives such as pubmed_fetch, pubmed_get, or search_pubmed. The only usage-adjacent hint is that use_history stores the search on the Entrez History server, which is a parameter behavior rather than routing 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?

With no annotations, the description carries the full burden. It discloses that it returns PMIDs exactly as NCBI returns them and mentions the reproducibility benefit of query_translation. However, it doesn't cover rate limits, authentication, error behavior, or whether results are cached, and the fact that it's a search tool implies a read-only profile that could be stated explicitly.

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 front-loaded with the core purpose, followed by a compact argument list and return summary. Every section earns its place, though the Args block is on the verbose side for a description and could be slightly trimmed.

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

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

For a 5-parameter search tool with no annotations and no output schema, the description covers inputs thoroughly and even describes the return payload (pmids, total_matches, query_translation). It lacks sibling differentiation and some operational behavior (rate limits, authentication), but overall it is nearly complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it does so well: it documents each parameter (query syntax with MeSH/Boolean, max_results range and default, sort options, date_from/date_to as publication-year bounds) and even explains returned metadata (total_matches, query_translation). This adds substantial meaning beyond the bare schema titles.

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 a specific verb and resource ('Search PubMed (NCBI esearch) and return PMIDs exactly as NCBI returns them'), which is clear. However, it doesn't distinguish itself from the sibling 'pubmed_search' or 'search_with_access', leaving ambiguity about which search tool to choose in the presence of similarly named siblings.

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 argument formats but provides no guidance on when to use this tool versus alternatives like pubmed_search or pubmed_fetch. No explicit when/when-not or alternative routing is present, leaving the agent to infer 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?

With no annotations, the description carries the full burden and does useful work: it discloses a real constraint not present in the schema ('max_results is capped at 100 here') and describes the result categorization into four lists, which tells the agent how to interpret the response. It still omits error behavior, whether access lookups are rate-limited or slow, and any explicit read-only statement.

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?

Front-loads the core purpose in one sentence, then gives the cap and return shape efficiently. No filler, though the cap sentence sits between purpose and returns rather than at the end.

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?

Because there is no output schema, describing the returned fields and the four categorization lists is necessary and is provided. However, with 5 parameters at 0% schema coverage and no annotations, the missing semantics for sort/date_from/date_to leave an agent guessing about filtering behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for five parameters, and the description only adds meaning for max_results (the 100 cap). The sort, date_from, and date_to parameters are entirely undocumented in both schema and description, so the description fails to compensate for the coverage gap.

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 a specific verb and resource ('Run a PubMed search') plus the distinguishing value-add ('report for every hit whether a legal open-access PDF exists or the paper looks paywalled'). This differentiates it from plain search siblings, though it never names pubmed_search or search_pubmed as the alternative to pick when access status is not needed.

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?

Usage context is only implied: the user picks this tool when they want OA status alongside search results, and the description mentions search_pubmed as the source of the shared return fields. There is no explicit when-to-use/when-not guidance relative to siblings like search_pubmed or check_access, so the agent must infer the routing.

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