Pubmed Search Articles

Previous value: -"Filter by author name (e.g. \"Smith J\")"New value: +"Filter by author name (e.g. \"Smith J\"). An empty string applies no filter; a value of only whitespace, invisible characters, markup, parentheses, brackets, or double quotes is rejected."

Previous value: -"Filter by date range. The filter is applied only when both `minDate` and `maxDate` are non-empty; either one empty disables the entire date range."New value: +"Filter by date range. The filter is applied only when both `minDate` and `maxDate` are non-empty; either one empty disables the entire date range. A partial date covers its whole year or month, and a range whose `minDate` falls after its `maxDate` is rejected: `2024/06` to `2024` is valid, `2024/07` to `2024/06/30` is not."

Previous value: -"End date (YYYY/MM/DD, YYYY/MM, or YYYY); empty string disables this bound"New value: +"End date (YYYY/MM/DD, YYYY/MM, or YYYY); empty string disables this bound. Must be a real calendar date — `2023/02/29` is rejected."

Previous value: -"Start date (YYYY/MM/DD, YYYY/MM, or YYYY); empty string disables this bound"New value: +"Start date (YYYY/MM/DD, YYYY/MM, or YYYY); empty string disables this bound. Must be a real calendar date — `2023/02/29` is rejected."

Previous value: -"Filter by journal name"New value: +"Filter by journal name. An empty string applies no filter; a value of only whitespace, invisible characters, markup, parentheses, brackets, or double quotes is rejected."

Previous value: -"Filter by language (e.g. \"english\")"New value: +"Filter by language (e.g. \"english\"). An empty string applies no filter; a value of only whitespace, invisible characters, markup, parentheses, brackets, or double quotes is rejected."

Previous value: -"Filter by MeSH terms. Multiple terms are AND'd — all must match."New value: +"Filter by MeSH terms. Multiple terms are AND'd — all must match. Empty strings are skipped; an element of only whitespace, invisible characters, markup, parentheses, brackets, or double quotes is rejected."

Previous value: -"Filter by publication type (e.g. \"Review\", \"Clinical Trial\", \"Meta-Analysis\"). Multiple values are OR'd — any match qualifies."New value: +"Filter by publication type (e.g. \"Review\", \"Clinical Trial\", \"Meta-Analysis\"). Multiple values are OR'd — any match qualifies. Empty strings are skipped; an element of only whitespace, invisible characters, markup, parentheses, brackets, or double quotes is rejected."

Previous value: -"PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup, bracketed field tags (`[pdat]`), and parentheses are removed is rejected rather than sent to PubMed as an empty term."New value: +"PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup, bracketed field tags (`[pdat]`), parentheses, and invisible characters such as a zero-width space are disregarded is rejected rather than sent to PubMed."

Previous value: -"Machine-readable failure mode. Declared by this tool: `queue_full`: The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429). `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and anything the tool strips before searching, are removed — so NCBI would receive a blank term. pubmed_search_articles strips markup, bracketed field tags, and parentheses, so a bare field tag such as `[pdat]` or empty parentheses `()` count as blank there. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `queue_full`: The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429). `ncbi_unreachable`: NCBI E-utilities failed on every attempt the retry budget allowed — retries ran out, or the next backoff would overrun the total deadline. `ncbi_rate_limited`: NCBI answered HTTP 429 (too many requests) and the call stopped on it — retries ran out, the next backoff would overrun the total deadline, or the Retry-After NCBI named outlasts the time left or the 30-second backoff cap. `ncbi_deadline_exceeded`: The total NCBI request deadline expired before NCBI answered successfully — mid-request, while queued, or during a retry backoff. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query contains no search term: nothing is left once whitespace and invisible characters such as a zero-width space are disregarded. pubmed_search_articles and pubmed_europepmc_search first decode HTML entities and also disregard markup and parentheses, so `()`, `<b></b>`, and `&nbsp;` hold no term there; pubmed_search_articles also disregards bracketed field tags such as `[pdat]`. `invalid_date_range`: A `dateRange` bound is not a real calendar date — a month outside 01–12, day 00, or a day past the end of its month such as `2023/02/29` — or `minDate` falls after `maxDate` once PubMed expands each partial date: `minDate` from the start of its year or month, `maxDate` to the end. `blank_filter`: An `author`, `journal`, or `language` value, or a `publicationTypes` or `meshTerms` element, holds no term once markup is removed and HTML entities are decoded — only whitespace, invisible characters such as a zero-width space, parentheses, brackets, or double quotes are left, as in `()` or `\"\"` — so its field clause would carry no term. An exactly-empty string is not blank here; it sets no filter. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "queue_full",
-  "ncbi_unreachable",
-  "ncbi_deadline_exceeded",
-  "ncbi_invalid_response",
-  "ncbi_resource_not_found",
-  "blank_query"
-]New value: +[
+  "queue_full",
+  "ncbi_unreachable",
+  "ncbi_rate_limited",
+  "ncbi_deadline_exceeded",
+  "ncbi_invalid_response",
+  "ncbi_resource_not_found",
+  "blank_query",
+  "invalid_date_range",
+  "blank_filter"
+]

Previous value: -"PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup is stripped is rejected rather than sent to PubMed as an empty term."New value: +"PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup, bracketed field tags (`[pdat]`), and parentheses are removed is rejected rather than sent to PubMed as an empty term."

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "query",
-      "offset",
-      "pmids",
-      "summaries",
-      "searchUrl",
-      "effectiveQuery",
-      "totalCount",
-      "appliedFilters"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "query",
+      "offset",
+      "pmids",
+      "summaries",
+      "searchUrl",
+      "totalCount",
+      "effectiveQuery",
+      "appliedFilters"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Previous value: -"Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `queue_full`: The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429). `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and anything the tool strips before searching, are removed — so NCBI would receive a blank term. pubmed_search_articles strips markup, bracketed field tags, and parentheses, so a bare field tag such as `[pdat]` or empty parentheses `()` count as blank there. Other values are possible when a failure originates below the handler."

Previous value: -"PubMed search query (supports full NCBI syntax)"New value: +"PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup is stripped is rejected rather than sent to PubMed as an empty term."

Previous value: -"Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "queue_full",
-  "ncbi_unreachable",
-  "ncbi_deadline_exceeded",
-  "ncbi_invalid_response",
-  "ncbi_resource_not_found"
-]New value: +[
+  "queue_full",
+  "ncbi_unreachable",
+  "ncbi_deadline_exceeded",
+  "ncbi_invalid_response",
+  "ncbi_resource_not_found",
+  "blank_query"
+]

Previous value: -"Formatted author string"New value: +"Formatted author string — the first three of the record's own authors, then \"et al.\". On an NCBI Bookshelf chapter these are the chapter's authors; the book's editors are reported separately in `editors`."

Added value: +{
+  "description": "Title of the book an NCBI Bookshelf record belongs to, e.g. \"GeneReviews(®)\". Present instead of `source` on a book record; absent on a journal article.",
+  "type": "string"
+}

Added value: +{
+  "description": "What PubMed classifies this record as: \"chapter\" or \"book\" for an NCBI Bookshelf record, \"citation\" for an ordinary journal article. Absent when PubMed supplies none.",
+  "type": "string"
+}

Added value: +{
+  "description": "Editors of the containing book, kept out of `authors` so they cannot displace the record's own authors. Absent on a journal article and on a book that credits no editors.",
+  "items": {
+    "description": "One editor, \"Surname Initials\" as ESummary renders it",
+    "type": "string"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "Publisher of the book an NCBI Bookshelf record belongs to. Present only on a book record; absent on a journal article.",
+  "type": "string"
+}

Previous value: -"Journal source"New value: +"Journal the article appeared in. Absent on an NCBI Bookshelf record, which has no journal — its venue is in `bookTitle` and `publisherName` instead, and `docType` says which kind of record it is."

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "query",
+      "offset",
+      "pmids",
+      "summaries",
+      "searchUrl",
+      "effectiveQuery",
+      "totalCount",
+      "appliedFilters"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "queue_full",
+            "ncbi_unreachable",
+            "ncbi_deadline_exceeded",
+            "ncbi_invalid_response",
+            "ncbi_resource_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "query",
-  "offset",
-  "pmids",
-  "summaries",
-  "searchUrl",
-  "effectiveQuery",
-  "totalCount",
-  "appliedFilters"
-]

Previous value: -"Result offset for pagination (0-based)"New value: +"Result offset for pagination (0-based). PubMed serves at most the first 9999 records of a result set, so this caps at 9998; narrow the query or add filters to reach anything beyond it."

Previous value: -9007199254740991New value: +9998

Previous value: -"Fetch brief summaries for top N results (0 = PMIDs only)"New value: +"Fetch brief summaries for top N results (0 = PMIDs only). Above the 50 cap, pass the remaining PMIDs to pubmed_fetch_articles."

Previous value: -"Optional guidance when results are empty or paging overshot — e.g. how to broaden filters or reset offset. Absent on successful result pages."New value: +"Optional guidance when the result set does not reflect what was asked for — a field tag PubMed ignored, a phrase it matched nothing for, a dateRange dropped for having one bound, no matches at all, or paging past the end. Absent when nothing applies."

Previous value: -"DOI"New value: +"DOI, cased as NCBI reports it. DOIs are case-insensitive by spec and no case normalization is applied here, so casing can differ from a Europe PMC-sourced `doi` — compare the two case-insensitively."

Added value: +{
+  "description": "Total matching articles",
+  "type": "number"
+}

Removed value: -{
-  "description": "Total matching articles",
-  "type": "number"
-}

Previous value: -[
-  "query",
-  "offset",
-  "pmids",
-  "summaries",
-  "searchUrl",
-  "effectiveQuery",
-  "totalFound",
-  "appliedFilters"
-]New value: +[
+  "query",
+  "offset",
+  "pmids",
+  "summaries",
+  "searchUrl",
+  "effectiveQuery",
+  "totalCount",
+  "appliedFilters"
+]

Previous value: -[
-  "query",
-  "effectiveQuery",
-  "appliedFilters",
-  "totalFound",
-  "offset",
-  "pmids",
-  "summaries",
-  "searchUrl"
-]New value: +[
+  "query",
+  "offset",
+  "pmids",
+  "summaries",
+  "searchUrl",
+  "effectiveQuery",
+  "totalFound",
+  "appliedFilters"
+]

Removed value: -false

Added value: +{
+  "description": "Filter by author name (e.g. \"Smith J\")",
+  "type": "string"
+}

Removed value: -false

Previous value: -"Defines an optional date range for the search."New value: +"Filter by date range"

Previous value: -"The type of date to filter by: 'pdat' (Publication Date), 'mdat' (Modification Date), 'edat' (Entrez Date). Default is 'pdat'."New value: +"Date type: pdat (publication), mdat (modification), edat (entrez)"

Previous value: -"The end date for the search range (YYYY, YYYY/MM, or YYYY/MM/DD)."New value: +"End date (YYYY/MM/DD, YYYY/MM, or YYYY)"

Removed value: -"^\\d{4}(\\/\\d{2}(\\/\\d{2})?)?$"

Previous value: -"The start date for the search range (YYYY, YYYY/MM, or YYYY/MM/DD)."New value: +"Start date (YYYY/MM/DD, YYYY/MM, or YYYY)"

Removed value: -"^\\d{4}(\\/\\d{2}(\\/\\d{2})?)?$"

Added value: +[
+  "minDate",
+  "maxDate"
+]

Removed value: -{
-  "default": 0,
-  "description": "Number of top PMIDs for which to fetch brief summaries using ESummary. Set to 0 to disable. Max 50. Default 0.",
-  "maximum": 50,
-  "minimum": 0,
-  "type": "integer"
-}

Removed value: -{
-  "description": "An array of publication types to filter by (e.g., [\"Review\", \"Clinical Trial\"]).",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

Added value: +{
+  "description": "Only include free full text articles",
+  "type": "boolean"
+}

Added value: +{
+  "description": "Only include articles with abstracts",
+  "type": "boolean"
+}

Added value: +{
+  "description": "Filter by journal name",
+  "type": "string"
+}

Added value: +{
+  "description": "Filter by language (e.g. \"english\")",
+  "type": "string"
+}

Previous value: -"Maximum number of articles to retrieve. Corresponds to ESearch's 'retmax' parameter. Default is 20, max is 1000."New value: +"Maximum results to return"

Removed value: -0

Added value: +1

Added value: +{
+  "description": "Filter by MeSH terms",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Added value: +{
+  "default": 0,
+  "description": "Result offset for pagination (0-based)",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

Added value: +{
+  "description": "Filter by publication type (e.g. \"Review\", \"Clinical Trial\", \"Meta-Analysis\")",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "PubMed search query (supports full NCBI syntax)",
+  "minLength": 1,
+  "type": "string"
+}

Removed value: -{
-  "description": "The primary keyword or phrase to search for in PubMed. Must be at least 3 characters long.",
-  "minLength": 3,
-  "type": "string"
-}

Added value: +{
+  "default": "relevance",
+  "description": "Sort order: relevance (default), pub_date (newest first), author, or journal",
+  "enum": [
+    "relevance",
+    "pub_date",
+    "author",
+    "journal"
+  ],
+  "type": "string"
+}

Removed value: -{
-  "default": "relevance",
-  "description": "Sorting criteria for results. Options: 'relevance' (default), 'pub_date', 'author', 'journal_name'.",
-  "enum": [
-    "relevance",
-    "pub_date",
-    "author",
-    "journal_name"
-  ],
-  "type": "string"
-}

Added value: +{
+  "description": "Filter by species",
+  "enum": [
+    "humans",
+    "animals"
+  ],
+  "type": "string"
+}

Added value: +{
+  "default": 0,
+  "description": "Fetch brief summaries for top N results (0 = PMIDs only)",
+  "maximum": 50,
+  "minimum": 0,
+  "type": "integer"
+}

Previous value: -[
-  "queryTerm"
-]New value: +[
+  "query"
+]

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "offset": {
+      "description": "Result offset used",
+      "type": "number"
+    },
+    "pmids": {
+      "description": "PubMed IDs",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "query": {
+      "description": "Original query",
+      "type": "string"
+    },
+    "searchUrl": {
+      "description": "PubMed search URL",
+      "type": "string"
+    },
+    "summaries": {
+      "description": "Brief summaries (empty array when summaryCount is 0)",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "authors": {
+            "description": "Formatted author string",
+            "type": "string"
+          },
+          "doi": {
+            "description": "DOI",
+            "type": "string"
+          },
+          "pmcId": {
+            "description": "PMC ID",
+            "type": "string"
+          },
+          "pmcUrl": {
+            "description": "PMC URL",
+            "type": "string"
+          },
+          "pmid": {
+            "description": "PubMed ID",
+            "type": "string"
+          },
+          "pubDate": {
+            "description": "Publication date",
+            "type": "string"
+          },
+          "pubmedUrl": {
+            "description": "PubMed URL",
+            "type": "string"
+          },
+          "source": {
+            "description": "Journal source",
+            "type": "string"
+          },
+          "title": {
+            "description": "Article title",
+            "type": "string"
+          }
+        },
+        "required": [
+          "pmid"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "totalFound": {
+      "description": "Total matching articles",
+      "type": "number"
+    }
+  },
+  "required": [
+    "query",
+    "totalFound",
+    "offset",
+    "pmids",
+    "summaries",
+    "searchUrl"
+  ],
+  "type": "object"
+}