Previous value: -"Citation to match against PubMed. Must include at least journal or year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match."New value: +"Citation to match against PubMed. Must include at least journal or a four-digit year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match."

Previous value: -"Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Cannot contain a pipe (\"|\") or a line break."New value: +"Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Must contain a visible character, and cannot contain a pipe (\"|\") or a line break."

Previous value: -"First page number. Cannot contain a pipe (\"|\") or a line break."New value: +"First page number. Must contain a visible character, and cannot contain a pipe (\"|\") or a line break."

Previous value: -"Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Cannot contain a pipe (\"|\") or a line break."New value: +"Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Must contain a visible character, and cannot contain a pipe (\"|\") or a line break."

Previous value: -"Volume number. Cannot contain a pipe (\"|\") or a line break."New value: +"Volume number. Must contain a visible character, and cannot contain a pipe (\"|\") or a line break."

Previous value: -"Publication year (e.g., \"1991\"). Cannot contain a pipe (\"|\") or a line break."New value: +"Publication year as four digits (e.g., \"1991\")."

Previous value: -"^[^|\\r\\n]*$"New value: +"^[ \\t]*\\d{4}[ \\t]*$"

Removed value: -[
-  {
-    "description": "Up to 25 citations, each matched independently.",
-    "items": {
-      "description": "Citation to match against PubMed. Must include at least journal or year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match.",
-      "properties": {
-        "authorName": {
-          "description": "Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Cannot contain a pipe (\"|\") or a line break.",
-          "pattern": "^[^|\\r\\n]*$",
-          "type": "string"
-        },
-        "firstPage": {
-          "description": "First page number. Cannot contain a pipe (\"|\") or a line break.",
-          "pattern": "^[^|\\r\\n]*$",
-          "type": "string"
-        },
-        "journal": {
-          "description": "Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Cannot contain a pipe (\"|\") or a line break.",
-          "pattern": "^[^|\\r\\n]*$",
-          "type": "string"
-        },
-        "key": {
-          "description": "Arbitrary label to track this citation in results. Auto-assigned if omitted. Echoed back unchanged and never sent to NCBI, so any character is accepted here.",
-          "type": "string"
-        },
-        "volume": {
-          "description": "Volume number. Cannot contain a pipe (\"|\") or a line break.",
-          "pattern": "^[^|\\r\\n]*$",
-          "type": "string"
-        },
-        "year": {
-          "description": "Publication year (e.g., \"1991\"). Cannot contain a pipe (\"|\") or a line break.",
-          "pattern": "^[^|\\r\\n]*$",
-          "type": "string"
-        }
-      },
-      "type": "object"
-    },
-    "maxItems": 25,
-    "minItems": 1,
-    "type": "array"
-  },
-  {
-    "description": "Citation to match against PubMed. Must include at least journal or year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match.",
-    "properties": {
-      "authorName": {
-        "description": "Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Cannot contain a pipe (\"|\") or a line break.",
-        "pattern": "^[^|\\r\\n]*$",
-        "type": "string"
-      },
-      "firstPage": {
-        "description": "First page number. Cannot contain a pipe (\"|\") or a line break.",
-        "pattern": "^[^|\\r\\n]*$",
-        "type": "string"
-      },
-      "journal": {
-        "description": "Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Cannot contain a pipe (\"|\") or a line break.",
-        "pattern": "^[^|\\r\\n]*$",
-        "type": "string"
-      },
-      "key": {
-        "description": "Arbitrary label to track this citation in results. Auto-assigned if omitted. Echoed back unchanged and never sent to NCBI, so any character is accepted here.",
-        "type": "string"
-      },
-      "volume": {
-        "description": "Volume number. Cannot contain a pipe (\"|\") or a line break.",
-        "pattern": "^[^|\\r\\n]*$",
-        "type": "string"
-      },
-      "year": {
-        "description": "Publication year (e.g., \"1991\"). Cannot contain a pipe (\"|\") or a line break.",
-        "pattern": "^[^|\\r\\n]*$",
-        "type": "string"
-      }
-    },
-    "type": "object"
-  }
-]

Previous value: -"Citations to look up — an array of up to 25, or a single citation object. More fields = better match accuracy."New value: +"Citations to look up, 1–25, each matched independently. More fields = better match accuracy."

Added value: +{
+  "description": "Citation to match against PubMed. Must include at least journal or year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match.",
+  "properties": {
+    "authorName": {
+      "description": "Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Cannot contain a pipe (\"|\") or a line break.",
+      "pattern": "^[^|\\r\\n]*$",
+      "type": "string"
+    },
+    "firstPage": {
+      "description": "First page number. Cannot contain a pipe (\"|\") or a line break.",
+      "pattern": "^[^|\\r\\n]*$",
+      "type": "string"
+    },
+    "journal": {
+      "description": "Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Cannot contain a pipe (\"|\") or a line break.",
+      "pattern": "^[^|\\r\\n]*$",
+      "type": "string"
+    },
+    "key": {
+      "description": "Arbitrary label to track this citation in results. Auto-assigned if omitted. Echoed back unchanged and never sent to NCBI, so any character is accepted here.",
+      "type": "string"
+    },
+    "volume": {
+      "description": "Volume number. Cannot contain a pipe (\"|\") or a line break.",
+      "pattern": "^[^|\\r\\n]*$",
+      "type": "string"
+    },
+    "year": {
+      "description": "Publication year (e.g., \"1991\"). Cannot contain a pipe (\"|\") or a line break.",
+      "pattern": "^[^|\\r\\n]*$",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Added value: +25

Added value: +1

Added value: +"array"

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). 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). 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_rate_limited",
+  "ncbi_deadline_exceeded",
+  "ncbi_invalid_response",
+  "ncbi_resource_not_found"
+]

Added value: +[
+  {
+    "description": "Up to 25 citations, each matched independently.",
+    "items": {
+      "description": "Citation to match against PubMed. Must include at least journal or year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match.",
+      "properties": {
+        "authorName": {
+          "description": "Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Cannot contain a pipe (\"|\") or a line break.",
+          "pattern": "^[^|\\r\\n]*$",
+          "type": "string"
+        },
+        "firstPage": {
+          "description": "First page number. Cannot contain a pipe (\"|\") or a line break.",
+          "pattern": "^[^|\\r\\n]*$",
+          "type": "string"
+        },
+        "journal": {
+          "description": "Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Cannot contain a pipe (\"|\") or a line break.",
+          "pattern": "^[^|\\r\\n]*$",
+          "type": "string"
+        },
+        "key": {
+          "description": "Arbitrary label to track this citation in results. Auto-assigned if omitted. Echoed back unchanged and never sent to NCBI, so any character is accepted here.",
+          "type": "string"
+        },
+        "volume": {
+          "description": "Volume number. Cannot contain a pipe (\"|\") or a line break.",
+          "pattern": "^[^|\\r\\n]*$",
+          "type": "string"
+        },
+        "year": {
+          "description": "Publication year (e.g., \"1991\"). Cannot contain a pipe (\"|\") or a line break.",
+          "pattern": "^[^|\\r\\n]*$",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "maxItems": 25,
+    "minItems": 1,
+    "type": "array"
+  },
+  {
+    "description": "Citation to match against PubMed. Must include at least journal or year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match.",
+    "properties": {
+      "authorName": {
+        "description": "Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Cannot contain a pipe (\"|\") or a line break.",
+        "pattern": "^[^|\\r\\n]*$",
+        "type": "string"
+      },
+      "firstPage": {
+        "description": "First page number. Cannot contain a pipe (\"|\") or a line break.",
+        "pattern": "^[^|\\r\\n]*$",
+        "type": "string"
+      },
+      "journal": {
+        "description": "Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Cannot contain a pipe (\"|\") or a line break.",
+        "pattern": "^[^|\\r\\n]*$",
+        "type": "string"
+      },
+      "key": {
+        "description": "Arbitrary label to track this citation in results. Auto-assigned if omitted. Echoed back unchanged and never sent to NCBI, so any character is accepted here.",
+        "type": "string"
+      },
+      "volume": {
+        "description": "Volume number. Cannot contain a pipe (\"|\") or a line break.",
+        "pattern": "^[^|\\r\\n]*$",
+        "type": "string"
+      },
+      "year": {
+        "description": "Publication year (e.g., \"1991\"). Cannot contain a pipe (\"|\") or a line break.",
+        "pattern": "^[^|\\r\\n]*$",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  }
+]

Previous value: -"Citations to look up. More fields = better match accuracy."New value: +"Citations to look up — an array of up to 25, or a single citation object. More fields = better match accuracy."

Removed value: -{
-  "description": "Citation to match against PubMed. Must include at least journal or year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match.",
-  "properties": {
-    "authorName": {
-      "description": "Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Cannot contain a pipe (\"|\") or a line break.",
-      "pattern": "^[^|\\r\\n]*$",
-      "type": "string"
-    },
-    "firstPage": {
-      "description": "First page number. Cannot contain a pipe (\"|\") or a line break.",
-      "pattern": "^[^|\\r\\n]*$",
-      "type": "string"
-    },
-    "journal": {
-      "description": "Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Cannot contain a pipe (\"|\") or a line break.",
-      "pattern": "^[^|\\r\\n]*$",
-      "type": "string"
-    },
-    "key": {
-      "description": "Arbitrary label to track this citation in results. Auto-assigned if omitted. Echoed back unchanged and never sent to NCBI, so any character is accepted here.",
-      "type": "string"
-    },
-    "volume": {
-      "description": "Volume number. Cannot contain a pipe (\"|\") or a line break.",
-      "pattern": "^[^|\\r\\n]*$",
-      "type": "string"
-    },
-    "year": {
-      "description": "Publication year (e.g., \"1991\"). Cannot contain a pipe (\"|\") or a line break.",
-      "pattern": "^[^|\\r\\n]*$",
-      "type": "string"
-    }
-  },
-  "type": "object"
-}

Removed value: -25

Removed value: -1

Removed value: -"array"

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`: 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). Other values are possible when a failure originates below the handler."

Previous value: -"Author name, typically \"lastname initials\" (e.g., \"mann bj\")"New value: +"Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Cannot contain a pipe (\"|\") or a line break."

Added value: +"^[^|\\r\\n]*$"

Previous value: -"First page number"New value: +"First page number. Cannot contain a pipe (\"|\") or a line break."

Added value: +"^[^|\\r\\n]*$"

Previous value: -"Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\")"New value: +"Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Cannot contain a pipe (\"|\") or a line break."

Added value: +"^[^|\\r\\n]*$"

Previous value: -"Arbitrary label to track this citation in results. Auto-assigned if omitted."New value: +"Arbitrary label to track this citation in results. Auto-assigned if omitted. Echoed back unchanged and never sent to NCBI, so any character is accepted here."

Previous value: -"Volume number"New value: +"Volume number. Cannot contain a pipe (\"|\") or a line break."

Added value: +"^[^|\\r\\n]*$"

Previous value: -"Publication year (e.g., \"1991\")"New value: +"Publication year (e.g., \"1991\"). Cannot contain a pipe (\"|\") or a line break."

Added value: +"^[^|\\r\\n]*$"

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": [
+      "results",
+      "totalMatched",
+      "totalSubmitted",
+      "totalWarnings"
+    ]
+  },
+  {
+    "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: -[
-  "results",
-  "totalMatched",
-  "totalSubmitted",
-  "totalWarnings"
-]

Previous value: -"Citation to match against PubMed. Must include at least one bibliographic field (journal, year, volume, firstPage, or authorName)."New value: +"Citation to match against PubMed. Must include at least journal or year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match."

Previous value: -"Citation to match against PubMed"New value: +"Citation to match against PubMed. Must include at least one bibliographic field (journal, year, volume, firstPage, or authorName)."

Previous value: -"PMIDs returned for AMBIGUOUS matches — candidate articles needing more citation fields to disambiguate. Parsed from the raw `AMBIGUOUS <csv>` detail string for programmatic consumption."New value: +"Candidate PMIDs returned when the citation matched ambiguously. Add more bibliographic fields and retry to disambiguate, or fetch each candidate via pubmed_fetch_articles to pick the intended one."

Previous value: -"Non-fatal warnings about this match. ECitMatch weights journal+volume+page and tolerates author/year disagreement, so a returned PMID may not match the queried author or year — downstream code should key on `code` to decide whether to trust the PMID."New value: +"Non-fatal warnings about this match. A PMID may be returned even when the queried author or year disagrees with the matched article — verify before treating the PMID as authoritative."

Previous value: -"Machine-readable warning classifier for downstream filtering"New value: +"Machine-readable warning code"

Added value: +{
+  "description": "PMIDs returned for AMBIGUOUS matches — candidate articles needing more citation fields to disambiguate. Parsed from the raw `AMBIGUOUS <csv>` detail string for programmatic consumption.",
+  "items": {
+    "description": "PMID",
+    "type": "string"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "First author of the matched article (e.g., \"Husain M\"). Useful eyeball signal for verifying a match.",
+  "type": "string"
+}

Added value: +{
+  "description": "Non-fatal warnings about this match. ECitMatch weights journal+volume+page and tolerates author/year disagreement, so a returned PMID may not match the queried author or year — downstream code should key on `code` to decide whether to trust the PMID.",
+  "items": {
+    "additionalProperties": false,
+    "description": "Non-fatal warning about the match",
+    "properties": {
+      "code": {
+        "description": "Machine-readable warning classifier for downstream filtering",
+        "enum": [
+          "author_mismatch",
+          "year_mismatch"
+        ],
+        "type": "string"
+      },
+      "message": {
+        "description": "Human-readable description of the warning",
+        "type": "string"
+      }
+    },
+    "required": [
+      "code",
+      "message"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "Number of matched citations that carry at least one warning",
+  "type": "number"
+}

Previous value: -[
-  "results",
-  "totalMatched",
-  "totalSubmitted"
-]New value: +[
+  "results",
+  "totalMatched",
+  "totalSubmitted",
+  "totalWarnings"
+]

Added value: +"Citation to match against PubMed"

Added value: +"Per-citation match result"

Added value: +{
+  "description": "Additional detail returned by ECitMatch for non-exact matches",
+  "type": "string"
+}

Added value: +{
+  "description": "Lookup outcome classification for this citation",
+  "enum": [
+    "matched",
+    "not_found",
+    "ambiguous"
+  ],
+  "type": "string"
+}

Previous value: -[
-  "key",
-  "matched"
-]New value: +[
+  "key",
+  "matched",
+  "status"
+]