@cyanheads/pubmed-mcp-server 2.10.20 → 2.10.22

package/dist/mcp-server/tools/definitions/fetch-fulltext.tool.js

@@ -1,8 +1,9 @@
 /**
  * @fileoverview Full-text fetch tool. Resolves full-text articles through a
  * three-stage chain: NCBI PMC EFetch → Europe PMC `fullTextXML` → Unpaywall.
- * Accepts three input fields, alone or together, naming at most 10 distinct
- * identifiers between them:
+ * Accepts three input fields, alone or together, naming at most 50 distinct
+ * identifiers between them. The first 10 in routing order are fetched; the rest
+ * are returned unfetched in `overLimit`, before any upstream request:
  *
  *   - `pmcids` — fetch directly by PMC ID, once per record however it is
  *     spelled (`PMC123`, `pmc123`, `123`, zero-padded `PMC0123`), and reported
@@ -17,12 +18,16 @@
  *     DOIs are case-insensitive: every casing of one DOI runs the chain once,
  *     and `unavailable[]` reports each casing as the caller wrote it.
  *
+ * The singular `pmcid`, `pmcId`, `pmid`, and `doi` are unadvertised aliases of
+ * these fields, and a lone string under any of them reads as a one-element
+ * array. (#221)
+ *
  * Routing runs `pmcids`, then `pmids`, then `dois`. Every tier keys its work on
  * the record — PMC on the PMCID, Europe PMC on the search hit's `source` + `id`,
  * Unpaywall on the lowercased DOI — and the first id to reach a record owns it:
  * a later id naming the same article joins the owner's chain as another caller
- * id, so the article is fetched and returned once. Each `unavailable[]` entry
- * and deferred id carries the field its id was sent in.
+ * id, so the article is fetched and returned once. Each `unavailable[]` entry,
+ * deferred id, and over-limit id carries the field its id was sent in.
  *
  * Output uses a discriminated union on `source` (`pmc` | `unpaywall`) with an
  * extra `viaSource` discriminator that records which layer produced the
@@ -50,7 +55,7 @@ import { findAll, findOne } from '../../../services/ncbi/parsing/pmc-xml-helpers
 import { toDisplayText } from '../../../services/ncbi/parsing/text-helpers.js';
 import { ensureArray } from '../../../services/ncbi/parsing/xml-helpers.js';
 import { getUnpaywallService, } from '../../../services/unpaywall/unpaywall-service.js';
-import { fitWholeItems } from './_budget.js';
+import { buildDeferralNotice, fitWholeItems } from './_budget.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, SCHEMA_SCHOLARLY_ARTICLE } from './_concepts.js';
 import { doiStringSchema, normalizePmid, pmcidStringSchema, pmidStringSchema } from './_schemas.js';
 import { escapeMarkdownInline, escapeMarkdownTableCell, sliceAtWordBoundary } from './_text.js';
@@ -286,6 +291,28 @@ function applyAssetFilters(article, filters) {
     const surviving = matchedSectionTitles(article.sections, filters.sections.map(lowerCase));
     return withAssets(article, assets.filter((a) => a.sectionTitle !== undefined && surviving.has(a.sectionTitle)));
 }
+/**
+ * The top-level sections the `sections` filter and the `maxSections` slice
+ * select, in order. Both act on each top-level section independently or cut a
+ * prefix, so applied to the body alone this returns exactly the body prefix of
+ * what it returns for body plus back matter — which is how {@link
+ * bodySectionCount} finds where the back matter starts.
+ */
+function selectSections(sections, filters) {
+    const pruned = filters.sections?.length
+        ? pruneSections(sections, filters.sections.map(lowerCase))
+        : sections;
+    return filters.maxSections === undefined ? pruned : pruned.slice(0, filters.maxSections);
+}
+/**
+ * How many leading entries of the filtered `sections` are body sections, the
+ * rest being back matter: the filter applied to the parsed body alone. The depth
+ * clamp that follows the filter maps sections one to one, so the count holds for
+ * the filtered article. (#206)
+ */
+function bodySectionCount(parsed, filters) {
+    return selectSections(parsed.sections, filters).length;
+}
 /**
  * Apply the requested section/reference/table/asset filters, then clamp the
  * section tree to the depth the output schema carries. All of it runs here so every path
@@ -303,13 +330,7 @@ function applyAssetFilters(article, filters) {
  * folded-away section survives in the text it was folded into. (#111, #130)
  */
 function applyPmcFilters(article, filters) {
-    let out = article;
-    if (filters.sections?.length) {
-        out = { ...out, sections: pruneSections(out.sections, filters.sections.map(lowerCase)) };
-    }
-    if (filters.maxSections !== undefined) {
-        out = { ...out, sections: out.sections.slice(0, filters.maxSections) };
-    }
+    let out = { ...article, sections: selectSections(article.sections, filters) };
     if (!filters.includeReferences) {
         const { references: _, ...rest } = out;
         out = rest;
@@ -319,11 +340,12 @@ function applyPmcFilters(article, filters) {
     return { ...out, sections: clampSectionDepth(out.sections) };
 }
 /**
- * True when a `sections` filter removed every body section from an article that
- * actually had sections upstream — the signal that the requested headings
- * matched nothing, as opposed to the article genuinely shipping no body. Only
- * the `sections` filter can zero a non-empty list: `maxSections` carries a
- * `.min(1)` floor, so it never reduces to zero. (#80)
+ * True when a `sections` filter removed every section, back matter included,
+ * from an article that actually had sections upstream — the signal that the
+ * requested headings matched nothing, as opposed to the article genuinely
+ * shipping no body. Only the `sections` filter can zero a non-empty list:
+ * `maxSections` carries a `.min(1)` floor, so it never reduces to zero. (#80,
+ * #206)
  */
 function isSectionFilterMiss(before, after, sectionFilter) {
     return (Boolean(sectionFilter?.length) && before.sections.length > 0 && after.sections.length === 0);
@@ -335,10 +357,21 @@ function isSectionFilterMiss(before, after, sectionFilter) {
  * while carrying nothing to read. Distinct from {@link isSectionFilterMiss},
  * which needs a non-empty pre-filter body: the two never overlap. Evaluated
  * against the *pre-filter* article so a `sections` filter can't be mistaken for
- * an upstream absence. (#86)
+ * an upstream absence, and before {@link withBackMatter}, so acknowledgments and
+ * a data-availability note alone are no body and the chain still moves on to the
+ * next tier. (#86, #206)
+ */
+function isBodylessArticle(parsed) {
+    return parsed.sections.length === 0;
+}
+/**
+ * The parsed article with its back-matter sections appended after the body
+ * ones, where every filter, slice, and budget downstream treats them as ordinary
+ * sections, and with no `backSections` field of its own left to reach the
+ * output. (#206)
  */
-function isBodylessArticle(before) {
-    return before.sections.length === 0;
+function withBackMatter({ backSections, ...article }) {
+    return backSections ? { ...article, sections: [...article.sections, ...backSections] } : article;
 }
 /** Pick the best human-readable identifier for an article, for recovery notices
  *  and character-budget accounting. Treats empty strings as absent — EPMC-only
@@ -359,7 +392,7 @@ function articleDisplayId(a) {
 function buildSectionFilterMissNotice(affectedIds, sectionFilter) {
     const terms = sectionFilter.join(', ');
     const subject = affectedIds.length === 1 ? `article ${affectedIds[0]}` : `articles ${affectedIds.join(', ')}`;
-    return `No section or subsection title, at any nesting depth, matched the requested section filter (${terms}) for ${subject}. The full text was retrieved but every body section was filtered out. Retry without \`sections\`, or filter on broader headings such as Introduction, Methods, Results, or Discussion.`;
+    return `No section or subsection title, at any nesting depth, matched the requested section filter (${terms}) for ${subject}. The full text was retrieved but every section, back matter included, was filtered out. Retry without \`sections\`, or filter on broader headings such as Introduction, Methods, Results, or Discussion.`;
 }
 /**
  * Compose the recovery notice for identifiers whose only retrievable record was
@@ -410,12 +443,16 @@ const SectionSchema = z
     text: z.string().describe('Section body text'),
     subsections: z.array(SubsectionSchema).optional().describe('Nested subsections'),
 })
-    .describe('Article body section');
+    .describe('Article section, from the body or from the back matter after it');
 const AuthorSchema = z
     .object({
     collectiveName: z.string().optional().describe('Group name'),
     givenNames: z.string().optional().describe('Given names'),
     lastName: z.string().optional().describe('Last name'),
+    suffix: z
+        .string()
+        .optional()
+        .describe('Generational name suffix verbatim from the JATS `<suffix>` (e.g. "Jr", "IV"), never normalized. Absent when the deposit gives none.'),
 })
     .describe('Author entry');
 const JournalSchema = z
@@ -457,7 +494,10 @@ const ReferenceSchema = z
  */
 const TableSchema = z
     .object({
-    label: z.string().optional().describe('Table label as printed, e.g. `TABLE 1`'),
+    label: z
+        .string()
+        .optional()
+        .describe('Table label as printed, e.g. `TABLE 1`, less one trailing ` |`, `.` or `:` (`Table 1.` reads `Table 1`)'),
     caption: z.string().optional().describe('Caption text, with the label excluded'),
     id: z
         .string()
@@ -466,7 +506,7 @@ const TableSchema = z
     sectionTitle: z
         .string()
         .optional()
-        .describe('Title of the innermost section enclosing the table, wherever that section sits — body, `<back>` matter, or an appendix all count, and in back matter the section name is the only positional cue there is. Absent only for a table inside no section at all, such as a `<floats-group>` deposit.'),
+        .describe('Title of the innermost titled section enclosing the table — a body section or a back-matter one such as an appendix — as that section is titled in `sections`, or, for a heading nested deeper than `sections` carries, as its heading line inside the text of the section that contains it. A `sections` filter keeps the table with that section. In back matter the section name is the only positional cue there is. Absent for a table inside no titled section, such as a `<floats-group>` deposit.'),
     headerRowCount: z
         .number()
         .describe('How many leading `rows` entries are header rows — a `<thead>` block, or leading rows made entirely of `<th>`. 0 when the table declares none. Several header rows stack: read one column top to bottom for its full header path.'),
@@ -505,7 +545,10 @@ const AssetSchema = z
     assetType: z
         .enum(['figure', 'supplementary-material'])
         .describe('Which captioned element this came from — `figure` for a `<fig>`, `supplementary-material` for a `<supplementary-material>` deposit'),
-    label: z.string().optional().describe('Display label as printed, e.g. `Fig. 1`'),
+    label: z
+        .string()
+        .optional()
+        .describe('Display label as printed, e.g. `Fig. 1`, less one trailing ` |`, `.` or `:` (`Figure 1.` reads `Figure 1`). Some supplements carry a bare number (`1`), kept as deposited here'),
     caption: z.string().optional().describe('Caption text, with the label excluded'),
     id: z
         .string()
@@ -514,7 +557,7 @@ const AssetSchema = z
     sectionTitle: z
         .string()
         .optional()
-        .describe('Title of the innermost section enclosing the asset, wherever that section sits — body, `<back>` matter, or an appendix all count. Absent for an asset inside no section at all, such as a `<floats-group>` deposit.'),
+        .describe('Title of the innermost titled section enclosing the asset — a body section or a back-matter one such as an appendix — as that section is titled in `sections`, or, for a heading nested deeper than `sections` carries, as its heading line inside the text of the section that contains it. Absent for an asset inside no titled section, such as a `<floats-group>` deposit.'),
     href: z
         .string()
         .optional()
@@ -555,7 +598,9 @@ const PmcArticleSchema = z
     keywords: z.array(z.string()).optional().describe('Keywords'),
     articleType: z.string().optional().describe('Article type'),
     publicationDate: PublicationDateSchema.optional(),
-    sections: z.array(SectionSchema).describe('Article body sections'),
+    sections: z
+        .array(SectionSchema)
+        .describe('Article sections in source order: the body, then the back matter — acknowledgments, notes and declarations, footnotes, glossary, appendices. A back-matter element with no heading of its own is titled by its kind, such as `Footnotes` or `Appendix`.'),
     tables: z
         .array(TableSchema)
         .optional()
@@ -563,7 +608,7 @@ const PmcArticleSchema = z
     assets: z
         .array(AssetSchema)
         .optional()
-        .describe('Every `<fig>` and `<supplementary-material>` the article carries, in document order — from the body and from `<floats-group>`, `<back>` and appendices alike. Each one lifted from the body leaves a `[Figure: <label>]` or `[Supplementary: <label>]` marker at its position in the section text, so reading order survives the lift. Absent when the article deposits none, when `includeAssets` is false, or when a `sections` filter left none standing.'),
+        .describe('Every `<fig>` and `<supplementary-material>` the article carries, in document order — from the body and from `<floats-group>`, `<back>` and appendices alike. Each one lifted from a section, body or back matter, leaves a `[Figure: <label>]` or `[Supplementary: <label>]` marker at its position in the section text, so reading order survives the lift. Absent when the article deposits none, when `includeAssets` is false, or when a `sections` filter left none standing.'),
     references: z.array(ReferenceSchema).optional().describe('Reference list'),
     epmcId: z
         .string()
@@ -738,7 +783,7 @@ const TruncatedSectionSchema = z
         .optional()
         .describe('Per-subsection accounting for a shortened section, in document order, including subsections dropped for budget — where inside the section the cut landed. Absent when the section was returned whole or carries no subsections.'),
 })
-    .describe('Character accounting for one body section of a budgeted article');
+    .describe('Character accounting for one section of a budgeted article');
 const TruncatedArticleSchema = z
     .object({
     id: z
@@ -746,7 +791,7 @@ const TruncatedArticleSchema = z
         .describe('Identifier for the article — PMCID, PMID, DOI, or Europe PMC id, whichever the article carries first'),
     source: z
         .enum(['pmc', 'unpaywall'])
-        .describe('Which output shape was budgeted: `pmc` budgets body sections and subsections, `unpaywall` budgets the single `content` body'),
+        .describe('Which output shape was budgeted: `pmc` budgets sections and subsections, `unpaywall` budgets the single `content` body'),
     originalCharacters: z
         .number()
         .describe('Body characters this article carried before the budget pass'),
@@ -766,11 +811,11 @@ const TruncatedArticleSchema = z
     omittedAssets: z
         .number()
         .optional()
-        .describe('Figures and supplementary items this article dropped whole because the budget left no room once sections and tables were served. An asset is never returned with a truncated caption, so it is either returned complete or counted here. Absent when none were dropped.'),
+        .describe('Figures and supplementary items this article dropped whole because the budget left no room once body sections and tables were served. An asset is never returned with a truncated caption, so it is either returned complete or counted here. Absent when none were dropped.'),
     omittedAssetNames: z
         .array(z.string())
         .optional()
-        .describe("The dropped assets by name, in document order — each asset's label, else its `id`, else `asset <n>` for its position in the article. Contiguous for the same reason `omittedTableNames` is: admission stops at the first asset that did not fit rather than skipping ahead to a smaller one. Absent when none were dropped."),
+        .describe("The dropped assets by name, in document order — each asset's label (a bare-number label led by its type, `Supplementary material 1`), else its `id`, else `asset <n>` for its position in the article. Contiguous for the same reason `omittedTableNames` is: admission stops at the first asset that did not fit rather than skipping ahead to a smaller one. Absent when none were dropped."),
 })
     .describe('Character accounting for one article the budget shortened');
 const TruncationSchema = z
@@ -791,7 +836,7 @@ const TruncationSchema = z
         .describe('Body characters the shortened articles carry in this response'),
     omittedSections: z
         .number()
-        .describe('Body sections and subsections dropped entirely because an article budget was exhausted before reaching them. A dropped section counts once, together with its subsections. Always 0 in `outline` mode, which keeps every heading.'),
+        .describe('Sections and subsections, back matter included, dropped entirely because an article budget was exhausted before reaching them. Back matter is reached last, after tables and assets. A dropped section counts once, together with its subsections. Always 0 in `outline` mode, which keeps every heading.'),
     omittedTables: z
         .number()
         .optional()
@@ -822,24 +867,50 @@ const DeferredSchema = z
         .describe('The input field every deferred id was sent in — re-submit them as `pmids`, `pmcids`, or `dois` respectively. Matches the `idType` on `unavailable` entries. Absent when the deferred ids came from more than one field; `pmcids` / `pmids` / `dois` then group them.'),
     ids: z
         .array(z.string())
-        .describe('Identifiers of the deferred articles, in response order, keyed as they were requested (PMC IDs in `PMC<digits>` form). Re-call `pubmed_fetch_fulltext` with these under the `idType` field — or, when `idType` is absent, with the `pmcids` / `pmids` / `dois` lists below — and the same other inputs. Never contains an id from `unavailable`.'),
+        .describe('Identifiers of the deferred articles, in routing order — `pmcids`, then `pmids`, then `dois`, request order within each — keyed as they were requested (PMC IDs in `PMC<digits>` form). Re-call `pubmed_fetch_fulltext` with these under the `idType` field — or, when `idType` is absent, with the `pmcids` / `pmids` / `dois` lists below — and the same other inputs. Never contains an id from `unavailable`.'),
     pmcids: z
         .array(z.string())
         .optional()
-        .describe('The deferred ids sent as PMC IDs, in response order — re-submit them as `pmcids`. Present only when the deferred ids came from more than one field (so `idType` is absent) and one of them was a PMC ID.'),
+        .describe('The deferred ids sent as PMC IDs, in routing order — re-submit them as `pmcids`. Present only when the deferred ids came from more than one field (so `idType` is absent) and one of them was a PMC ID.'),
     pmids: z
         .array(z.string())
         .optional()
-        .describe('The deferred ids sent as PMIDs, in response order — re-submit them as `pmids`. Present only when the deferred ids came from more than one field (so `idType` is absent) and one of them was a PMID.'),
+        .describe('The deferred ids sent as PMIDs, in routing order — re-submit them as `pmids`. Present only when the deferred ids came from more than one field (so `idType` is absent) and one of them was a PMID.'),
     dois: z
         .array(z.string())
         .optional()
-        .describe('The deferred ids sent as DOIs, in response order — re-submit them as `dois`. Present only when the deferred ids came from more than one field (so `idType` is absent) and one of them was a DOI.'),
+        .describe('The deferred ids sent as DOIs, in routing order — re-submit them as `dois`. Present only when the deferred ids came from more than one field (so `idType` is absent) and one of them was a DOI.'),
     nextDeferredCharacters: z
         .number()
-        .describe('Serialized size of the next deferred article — the first entry in `ids`, where the response stopped. Raise `maxResponseCharacters` to at least this to make progress; a smaller article further down `ids` cannot be reached until this one fits.'),
+        .describe('Serialized size of the next deferred article — the first entry in `ids`, where the response stopped — and the continuation ceiling: re-calling with the deferred ids needs `maxResponseCharacters` ≥ this to return anything, and a smaller article further down `ids` cannot be reached until this one fits. Repeating this same call needs `maxResponseCharacters` ≥ `returnedCharacters` + this to return this article as well.'),
 })
     .describe('Continuation state for articles the whole-response budget withheld. Present only when `maxResponseCharacters` deferred at least one article.');
+const OverLimitSchema = z
+    .object({
+    limit: z
+        .number()
+        .describe('Distinct identifiers one call fetches. The first this many, in routing order — `pmcids`, then `pmids`, then `dois`, request order within each — were fetched; the ids below were not.'),
+    idType: z
+        .enum(['pmid', 'pmcid', 'doi'])
+        .optional()
+        .describe('The input field every over-limit id was sent in — re-submit them as `pmids`, `pmcids`, or `dois` respectively. Absent when the over-limit ids came from more than one field; `pmcids` / `pmids` / `dois` then group them.'),
+    ids: z
+        .array(z.string())
+        .describe('Identifiers past the per-call limit, none of them fetched, in routing order — each listed once, under the first spelling sent (PMC IDs in `PMC<digits>` form). Re-call `pubmed_fetch_fulltext` with these under the `idType` field — or, when `idType` is absent, with the `pmcids` / `pmids` / `dois` lists below — and the same other inputs, at most `limit` per call. Never contains an id from `unavailable` or `deferred`.'),
+    pmcids: z
+        .array(z.string())
+        .optional()
+        .describe('The over-limit ids sent as PMC IDs, in routing order — re-submit them as `pmcids`. Present only when the over-limit ids came from more than one field (so `idType` is absent) and one of them was a PMC ID.'),
+    pmids: z
+        .array(z.string())
+        .optional()
+        .describe('The over-limit ids sent as PMIDs, in routing order — re-submit them as `pmids`. Present only when the over-limit ids came from more than one field (so `idType` is absent) and one of them was a PMID.'),
+    dois: z
+        .array(z.string())
+        .optional()
+        .describe('The over-limit ids sent as DOIs, in routing order — re-submit them as `dois`. Present only when the over-limit ids came from more than one field (so `idType` is absent) and one of them was a DOI.'),
+})
+    .describe('Identifiers the call named past the per-call fetch limit, returned unfetched for a follow-up call. Present only when the call named more than `limit` distinct identifiers. Separate from `deferred`, which lists articles that were fetched but withheld by `maxResponseCharacters`.');
 /** True when the request asked for any budget at all. Without one, every budget
  *  helper returns its input untouched so the response is byte-identical. */
 function budgetRequested(budget) {
@@ -1045,11 +1116,16 @@ function allotSectionBudgets(sizes, budget) {
  * or cut — the budget spends on body text and table content, keeping every
  * article citable.
  *
- * Body sections are served first, then tables, then assets, each spending what
- * `maxCharacters` has left, in document order: an item that does not fit is
- * dropped whole and counted, never truncated into a partial grid or a caption cut
- * short. With no `maxCharacters` — a bare `maxCharactersPerSection` request —
- * nothing bounds either list and every entry is kept. (#111, #130)
+ * Body sections are served first, then tables, then assets, then back-matter
+ * sections, each spending what `maxCharacters` has left, in document order. A
+ * table or asset that does not fit is dropped whole and counted, never
+ * truncated into a partial grid or a caption cut short. Back matter comes last
+ * so it never displaces a table or figure: it is shortened or dropped the way
+ * body sections are, from whatever the rest left. The first `bodySections`
+ * entries of `article.sections` are the body; spend order aside, `sections` and
+ * the ledger stay in document order. With no `maxCharacters` — a bare
+ * `maxCharactersPerSection` request — nothing bounds the tables or assets and
+ * every entry is kept. (#111, #130, #206)
  *
  * Returns the article untouched (same object identity) when no budget was
  * requested or nothing exceeded it. A section or subsection left with zero
@@ -1057,7 +1133,7 @@ function allotSectionBudgets(sizes, budget) {
  * keeps it as a heading-only entry. Dropped nodes still appear in the accounting
  * so the caller can see which headings exist. (#81, #143)
  */
-function applyPmcBudget(article, budget) {
+function applyPmcBudget(article, budget, bodySections) {
     const tables = article.tables ?? [];
     const assets = article.assets ?? [];
     if (!budgetRequested(budget) ||
@@ -1068,31 +1144,37 @@ function applyPmcBudget(article, budget) {
     const tablesOriginal = tables.reduce((sum, table) => sum + tableCharacters(table), 0);
     const assetsOriginal = assets.reduce((sum, asset) => sum + assetCharacters(asset), 0);
     const originalCharacters = sizes.reduce((sum, size) => sum + size, 0) + tablesOriginal + assetsOriginal;
-    const allowances = allotSectionBudgets(sizes, budget);
     const kept = [];
     const sectionReports = [];
     let returnedCharacters = 0;
-    article.sections.forEach((section, i) => {
-        const fitted = fitFields(sectionTextFields(section), allowances[i] ?? 0);
-        const fit = fitSectionTree(section, fitted, { i: 0 }, budget.overflowMode);
-        returnedCharacters += fit.entry.returnedCharacters;
-        sectionReports.push(fit.entry);
-        if (fit.kept)
-            kept.push(fit.kept);
-    });
-    const omittedSections = countDroppedSections(sectionReports, budget.overflowMode);
-    // Sections are served first, then tables, then assets — each spending whatever
-    // `maxCharacters` has left. A bare per-section budget sets no total, so nothing
-    // bounds either list.
+    // Each stage spends whatever `maxCharacters` has left. A bare per-section
+    // budget sets no total, so nothing bounds the tables or assets.
     const remainingAllowance = () => budget.maxCharacters === undefined
         ? Number.POSITIVE_INFINITY
         : Math.max(budget.maxCharacters - returnedCharacters, 0);
+    const fitSections = (sections, total) => {
+        const allowances = allotSectionBudgets(sections.map(sectionCharacters), {
+            ...budget,
+            maxCharacters: total,
+        });
+        sections.forEach((section, i) => {
+            const fitted = fitFields(sectionTextFields(section), allowances[i] ?? 0);
+            const fit = fitSectionTree(section, fitted, { i: 0 }, budget.overflowMode);
+            returnedCharacters += fit.entry.returnedCharacters;
+            sectionReports.push(fit.entry);
+            if (fit.kept)
+                kept.push(fit.kept);
+        });
+    };
+    fitSections(article.sections.slice(0, bodySections), budget.maxCharacters);
     const fittedTables = fitWholeNamed(tables, remainingAllowance(), tableCharacters, tableDisplayName);
     returnedCharacters += fittedTables.spent;
     const omittedTables = fittedTables.omittedNames.length;
     const fittedAssets = fitWholeNamed(assets, remainingAllowance(), assetCharacters, assetDisplayName);
     returnedCharacters += fittedAssets.spent;
     const omittedAssets = fittedAssets.omittedNames.length;
+    fitSections(article.sections.slice(bodySections), budget.maxCharacters === undefined ? undefined : remainingAllowance());
+    const omittedSections = countDroppedSections(sectionReports, budget.overflowMode);
     if (returnedCharacters === originalCharacters &&
         omittedSections === 0 &&
         omittedTables === 0 &&
@@ -1145,7 +1227,23 @@ function tableDisplayName(table, index) {
 }
 /** How an asset is named in a notice: its label, else its id, else its position. */
 function assetDisplayName(asset, index) {
-    return asset.label ?? asset.id ?? `asset ${index + 1}`;
+    return assetLabelName(asset) ?? asset.id ?? `asset ${index + 1}`;
+}
+/** The word a bare-number asset label is named with, by asset type. */
+const ASSET_TYPE_NAMES = {
+    figure: 'Figure',
+    'supplementary-material': 'Supplementary material',
+};
+/**
+ * An asset's label as a name in a list or heading, its type leading a label that
+ * is a bare number: NIH-manuscript supplements are labelled `1`, which reads as a
+ * count among names (`7 asset(s) dropped whole: 1, Figure 1`). `label` and the
+ * prose marker keep the number as deposited — the marker (`[Supplementary: 1]`)
+ * names the kind already. (#240)
+ */
+function assetLabelName(asset) {
+    const { label } = asset;
+    return label && /^\d+$/.test(label) ? `${ASSET_TYPE_NAMES[asset.assetType]} ${label}` : label;
 }
 /**
  * Collect the returned tables that carry no cell values. Read off the articles
@@ -1225,33 +1323,38 @@ function buildTruncationNotice(truncation) {
     return `Full text was shortened to fit the requested character budget: ${truncation.returnedCharacters} of ${truncation.originalCharacters} body characters returned across ${subject} in ${truncation.mode} mode.${omitted}${omittedTables}${omittedAssets} See \`truncation\` for per-article and per-section counts, and raise ${knobs.join(' or ')} or narrow \`sections\` to retrieve more.`;
 }
 /**
- * Compose the recovery notice for articles the whole-response budget withheld.
- * Names what was spent, which identifiers are still retrievable, and the ceiling
- * the next call has to clear — so a caller reading only `content[]` can resume
- * without inspecting `deferred`. (#100)
+ * Compose the recovery notice for identifiers past the per-call fetch limit:
+ * how many were left unfetched, which ones, and where to resend them — so a
+ * caller reading only `content[]` can retrieve the rest without inspecting
+ * `overLimit`. (#222)
  */
-function buildDeferralNotice(deferred) {
-    const spent = deferred.returnedCharacters === 0
-        ? `The first article alone exceeds the requested maxResponseCharacters of ${deferred.maxResponseCharacters}, so none were returned.`
-        : `Response character budget reached: ${deferred.returnedCharacters} of ${deferred.maxResponseCharacters} characters returned.`;
-    const resend = deferred.idType
-        ? `Re-call pubmed_fetch_fulltext with those ids under \`${deferred.idType}s\``
-        : `Re-call pubmed_fetch_fulltext with each id under its own field (${deferredFieldLists(deferred)})`;
-    return `${spent} ${deferred.deferredCount} resolved article(s) were deferred whole: ${deferred.ids.join(', ')}. ${resend} to retrieve them, or raise maxResponseCharacters to at least ${deferred.nextDeferredCharacters} — the size of the next deferred article.`;
+function buildOverLimitNotice(overLimit) {
+    const resend = overLimit.idType
+        ? `Re-call pubmed_fetch_fulltext with those ids under \`${overLimit.idType}s\``
+        : `Re-call pubmed_fetch_fulltext with each id under its own field (${idFieldLists(overLimit)})`;
+    return `This call fetched the first ${overLimit.limit} distinct identifiers; ${overLimit.ids.length} more were not fetched: ${overLimit.ids.join(', ')}. ${resend}, at most ${overLimit.limit} per call, to retrieve them.`;
 }
 /**
- * The per-field lists of a deferral that spans fields, in field order —
+ * The per-field lists of ids handed back across fields, in field order —
  * `` `pmcids`: PMC1; `dois`: 10.1/x `` — or `''` when `idType` covers them all.
  */
-function deferredFieldLists(deferred) {
+function idFieldLists(group) {
     return ['pmcids', 'pmids', 'dois']
         .flatMap((field) => {
-        const ids = deferred[field];
+        const ids = group[field];
         return ids?.length ? [`\`${field}\`: ${ids.join(', ')}`] : [];
     })
         .join('; ');
 }
 // ─── Tool Definition ─────────────────────────────────────────────────────────
+/**
+ * Distinct identifiers one call fetches across `pmcids`, `pmids`, and `dois`,
+ * in routing order; the rest are returned unfetched in `overLimit`. Bounds the
+ * candidates every tier works per call. (#192, #222)
+ */
+const FETCH_LIMIT = 10;
+/** Distinct identifiers one call may name across the three fields. (#222) */
+const MAX_IDENTIFIERS = 50;
 /**
  * Compose the tool description for the fallback tiers enabled in this
  * deployment. PMC EFetch is always present; Europe PMC (`EUROPEPMC_ENABLED`)
@@ -1260,7 +1363,7 @@ function deferredFieldLists(deferred) {
  * recoveries that silently can't happen.
  */
 export function buildFulltextDescription(tiers) {
-    const base = 'Fetch full-text articles from PubMed Central with structured sections, tables, and references.';
+    const base = 'Fetch full-text articles from PubMed Central as structured sections — the body, then back matter such as acknowledgments, declarations, and appendices — with tables and references.';
     const epmcClause = 'Europe PMC `fullTextXML` (structured JATS for records with a PMC counterpart)';
     const unpaywallClause = 'Unpaywall — publisher-hosted or institutional open-access copies as HTML-as-Markdown or PDF-as-text';
     let fallback;
@@ -1284,13 +1387,11 @@ export function buildFulltextDescription(tiers) {
             : tiers.unpaywall
                 ? '; DOIs with no PMC copy recover via Unpaywall open access'
                 : '';
-    const input = `Name articles by \`pmcids\` (PMC IDs directly), \`pmids\` (PubMed IDs, auto-resolved), \`dois\` (DOIs, auto-resolved to PMC via the ID Converter${doiTail}), or any mix of the three — up to 10 distinct identifiers per call; an article several of them name is fetched and returned once.`;
+    const input = `Name articles by \`pmcids\` (PMC IDs directly), \`pmids\` (PubMed IDs, auto-resolved), \`dois\` (DOIs, auto-resolved to PMC via the ID Converter${doiTail}), or any mix of the three — up to ${MAX_IDENTIFIERS} distinct identifiers; the first ${FETCH_LIMIT} are fetched per call, the rest returned in \`overLimit\`; an article several of them name is fetched and returned once.`;
     const budget = 'Two independent character controls: `maxCharacters` caps body text per article, `maxResponseCharacters` caps the whole response and defers articles past the ceiling whole, listing them in `deferred.ids` for a follow-up call.';
     return `${base} ${fallback} ${input} ${budget}`;
 }
 const serverConfig = getServerConfig();
-/** Distinct identifiers one call may name across `pmcids`, `pmids`, and `dois`. (#192) */
-const MAX_IDENTIFIERS = 10;
 export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
     description: buildFulltextDescription({
         europePmc: serverConfig.europepmcEnabled,
@@ -1314,26 +1415,30 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             retryable: false,
         },
     ],
+    // Never advertised; rewritten to the canonical key before the schema parses.
+    // Singular spellings sibling tools and this tool's own output use; a lone
+    // string under one becomes a one-element array. (#221)
+    inputAliases: { pmcid: 'pmcids', pmcId: 'pmcids', pmid: 'pmids', doi: 'dois' },
     input: z
         .object({
         pmcids: z
             .array(pmcidStringSchema)
             .min(1)
-            .max(10)
+            .max(MAX_IDENTIFIERS)
             .optional()
-            .describe('PMC IDs to fetch (e.g. ["PMC9575052"]). Combinable with `pmids` and `dois` — at most 10 distinct identifiers across the three. PMC IDs with no retrievable full text fall through to Europe PMC, then to Unpaywall on the DOI the chain resolves for them.'),
+            .describe(`PMC IDs to fetch (e.g. ["PMC9575052"]). Combinable with \`pmids\` and \`dois\` — up to ${MAX_IDENTIFIERS} distinct identifiers across the three; the first ${FETCH_LIMIT} are fetched per call, the rest returned in \`overLimit\`. PMC IDs with no retrievable full text fall through to Europe PMC, then to Unpaywall on the DOI the chain resolves for them.`),
         pmids: z
             .array(pmidStringSchema)
             .min(1)
-            .max(10)
+            .max(MAX_IDENTIFIERS)
             .optional()
-            .describe('PubMed IDs. Combinable with `pmcids` and `dois` — at most 10 distinct identifiers across the three. Articles in PMC are returned as structured JATS; articles not in PMC fall through to Europe PMC (when EPMC has a `fullTextXML`), then to Unpaywall when `UNPAYWALL_EMAIL` is set and a DOI is available.'),
+            .describe(`PubMed IDs. Combinable with \`pmcids\` and \`dois\` — up to ${MAX_IDENTIFIERS} distinct identifiers across the three; the first ${FETCH_LIMIT} are fetched per call, the rest returned in \`overLimit\`. Articles in PMC are returned as structured JATS; articles not in PMC fall through to Europe PMC (when EPMC has a \`fullTextXML\`), then to Unpaywall when \`UNPAYWALL_EMAIL\` is set and a DOI is available.`),
         dois: z
             .array(doiStringSchema)
             .min(1)
-            .max(10)
+            .max(MAX_IDENTIFIERS)
             .optional()
-            .describe('DOIs to resolve (e.g. ["10.21203/rs.3.rs-9010375/v1"]), one per element. Combinable with `pmcids` and `pmids` — at most 10 distinct identifiers across the three. Resolved to a PMCID via the PMC ID Converter and returned as structured JATS when the article is in PMC; DOIs with no PMC counterpart (preprints, EPMC-only OA) fall through to Europe PMC, then Unpaywall, when those layers are enabled.'),
+            .describe(`DOIs to resolve (e.g. ["10.21203/rs.3.rs-9010375/v1"]), one per element. Combinable with \`pmcids\` and \`pmids\` — up to ${MAX_IDENTIFIERS} distinct identifiers across the three; the first ${FETCH_LIMIT} are fetched per call, the rest returned in \`overLimit\`. Resolved to a PMCID via the PMC ID Converter and returned as structured JATS when the article is in PMC; DOIs with no PMC counterpart (preprints, EPMC-only OA) fall through to Europe PMC, then Unpaywall, when those layers are enabled.`),
         includeReferences: z
             .boolean()
             .default(false)
@@ -1350,48 +1455,40 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             .number()
             .int()
             .min(1)
-            .max(50)
             .optional()
-            .describe('Maximum top-level body sections. Applies to `source=pmc` results only.'),
+            .describe('Maximum top-level sections. Back-matter sections count and follow the body, so a cap drops them first. Applies to `source=pmc` results only.'),
         sections: z
             .array(z.string())
             .optional()
-            .describe('Filter to specific sections by title (e.g. ["Introduction", "Methods", "Results", "Discussion"]). A term matches a section or subsection title at any nesting depth, case-insensitively, as a substring — "resul" matches "Results". A section whose own title matches is returned whole; one kept only because a nested subsection matched keeps its heading as a breadcrumb, with its own text cleared and only the matching branch beneath it. Tables and assets narrow with the filter: one whose section did not survive, or that names no section, is dropped. Empty strings are skipped, so `[""]` applies no filter; an element of only whitespace or invisible characters, such as a zero-width space, is rejected. Applies to `source=pmc` results only.'),
+            .describe('Filter to specific sections by title (e.g. ["Introduction", "Methods", "Results", "Discussion"]). A term matches a section or subsection title at any nesting depth, case-insensitively, as a substring — "resul" matches "Results". Back-matter sections match the same way: by their own titles, or by their kind when they carry neither a title nor a label — "appendix" matches a section titled "Appendix A", "footnotes" an untitled footnote group. A label is never matched, so an appendix labelled "Appendix A" under a title of its own matches only on that title. A section whose own title matches is returned whole; one kept only because a nested subsection matched keeps its heading as a breadcrumb, with its own text cleared and only the matching branch beneath it. Tables and assets narrow with the filter: one whose section did not survive, or that names no section, is dropped. Empty strings are skipped, so `[""]` applies no filter; an element of only whitespace or invisible characters, such as a zero-width space, is rejected. Applies to `source=pmc` results only.'),
         maxCharacters: z
             .number()
             .int()
             .min(1)
-            .max(1_000_000)
             .optional()
-            .describe('Per-article budget for body text, in characters. Counts `source=pmc` section and subsection text — which carries the inline blocks the parser renders in place, such as lists, definition lists, block quotes, boxed text, preformatted blocks and displayed formulae — plus table label, caption, cell and footnote text and asset label, caption and `href` text; or the `source=unpaywall` `content` body. Titles, abstracts, identifiers, and references are never counted or shortened. Shortened text ends at the last word boundary inside its allowance, so it can come back a few characters under it. The counted unit is that text alone — the Markdown grid `content[]` renders around the cells (pipes, padding, the divider row, headings) is scaffolding this budget does not measure, so a table renders longer than it costs here. Sections are served first, then tables, then assets, each spending what is left, in document order — admission stops at the first entry that does not fit, and every entry from there on is dropped whole rather than cut mid-row or returned with a shortened caption, counted in `truncation.omittedTables` / `truncation.omittedAssets` and named in `truncation.articles[].omittedTableNames` / `omittedAssetNames`. Applied after `sections`, `maxSections`, `includeReferences`, `includeTables`, and `includeAssets`, so semantic filtering is unaffected. This knob alone bounds only bodies: the response-wide ceiling it implies is this value times the number of articles returned, plus every uncounted field. Use `maxResponseCharacters` for a true whole-response ceiling. Omit for the full body.'),
+            .describe('Per-article budget for body text, in characters. Counts `source=pmc` section and subsection text — which carries the inline blocks the parser renders in place, such as lists, definition lists, block quotes, boxed text, preformatted blocks and displayed formulae — plus table label, caption, cell and footnote text and asset label, caption and `href` text; or the `source=unpaywall` `content` body. Titles, abstracts, identifiers, and references are never counted or shortened. Shortened text ends at the last word boundary inside its allowance, so it can come back a few characters under it. The counted unit is that text alone — the Markdown grid `content[]` renders around the cells (pipes, padding, the divider row, headings) is scaffolding this budget does not measure, so a table renders longer than it costs here. Body sections are served first, then tables, then assets, then back-matter sections, each spending what is left, in document order. For tables and assets, admission stops at the first entry that does not fit, and every entry from there on is dropped whole rather than cut mid-row or returned with a shortened caption, counted in `truncation.omittedTables` / `truncation.omittedAssets` and named in `truncation.articles[].omittedTableNames` / `omittedAssetNames`. Back matter takes only what remains and is shortened or dropped as body sections are; `sections` still returns it after the body. Applied after `sections`, `maxSections`, `includeReferences`, `includeTables`, and `includeAssets`, so semantic filtering is unaffected. This knob alone bounds only bodies: the response-wide ceiling it implies is this value times the number of articles returned, plus every uncounted field. Use `maxResponseCharacters` for a true whole-response ceiling. Omit for the full body.'),
         maxCharactersPerSection: z
             .number()
             .int()
             .min(1)
-            .max(1_000_000)
             .optional()
-            .describe('Budget for a single top-level body section, in characters, counting the section text plus its subsections. Combine with `maxCharacters` to cap both one section and the article; the tighter of the two wins. Applies to `source=pmc` results only.'),
+            .describe('Budget for a single top-level section, in characters, counting the section text plus its subsections. Combine with `maxCharacters` to cap both one section and the article; the tighter of the two wins. Applies to `source=pmc` results only.'),
         maxResponseCharacters: z
             .number()
             .int()
             .min(1)
-            .max(1_000_000)
             .optional()
-            .describe('Opt-in ceiling for the whole response, in characters — the true response-wide counterpart to the per-article `maxCharacters`. Each article is measured as the JSON record it is returned as, after every filter and the per-article body budget: title, abstract, body sections, references, identifiers, license and source metadata — every field it carries. One ledger covers all tiers, so PMC-, Europe PMC-, and Unpaywall-served articles spend the same budget. Articles are kept in response order until the next one would cross the ceiling; that article and the rest are deferred whole (never partially populated) and listed in `deferred.ids`. Response envelope fields — counts, `unavailable`, `truncation`, `deferred` itself — are not counted. Omit to return every resolved article.'),
+            .describe('Opt-in ceiling for the whole response, in characters — the true response-wide counterpart to the per-article `maxCharacters`. Each article is measured as the JSON record it is returned as, after every filter and the per-article body budget: title, abstract, sections, references, identifiers, license and source metadata — every field it carries. One ledger covers all tiers, so PMC-, Europe PMC-, and Unpaywall-served articles spend the same budget. Articles are kept in the order `articles` lists them until the next one would cross the ceiling; that article and the rest are deferred whole (never partially populated) and listed in `deferred.ids`. Response envelope fields — counts, `unavailable`, `truncation`, `deferred` itself — are not counted. Omit to return every resolved article.'),
         overflowMode: z
             .enum(['truncate', 'outline'])
             .default('truncate')
-            .describe('How to spend `maxCharacters` across an article that exceeds it. truncate: fill sections in document order, so early sections stay whole, the section the budget runs out in is cut, and every section or subsection past that point is dropped (counted in `truncation.omittedSections`). outline: split the budget evenly so every section and subsection keeps its heading, and an excerpt as far as the budget reaches — a heading the budget left empty is marked as such in the rendered text. Use it to survey what an article contains before requesting specific `sections`. Ignored when no budget is set, and identical for `source=unpaywall` bodies, which have no headings to preserve.'),
+            .describe('How to spend `maxCharacters` across an article that exceeds it. truncate: fill sections in document order, so early sections stay whole, the section the budget runs out in is cut, and every section or subsection past that point is dropped (counted in `truncation.omittedSections`). outline: split the budget evenly so every section and subsection keeps its heading, and an excerpt as far as the budget reaches — a heading the budget left empty is marked as such in the rendered text. In both modes the body sections spend the budget first and back-matter sections share what the body, tables, and assets leave. Use it to survey what an article contains before requesting specific `sections`. Ignored when no budget is set, and identical for `source=unpaywall` bodies, which have no headings to preserve.'),
     })
         // Counted in each field's canonical form, the one its chain keys on, so the
-        // cap is settled before any upstream request and holds every fallback tier
-        // to at most 10 candidates. (#192)
+        // ceiling is settled before any upstream request; the handler then fetches
+        // the first FETCH_LIMIT the same way. (#192, #222)
         .superRefine((v, refinement) => {
-        const distinct = new Set([
-            ...(v.pmcids ?? []).map((id) => `pmcid:${normalizePmcId(id)}`),
-            ...(v.pmids ?? []).map((id) => `pmid:${normalizePmid(id)}`),
-            ...(v.dois ?? []).map((id) => `doi:${id.toLowerCase()}`),
-        ]);
+        const distinct = new Set(requestedIds(v).map((r) => r.key));
         if (distinct.size === 0) {
             refinement.addIssue({
                 code: 'custom',
@@ -1401,38 +1498,41 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         else if (distinct.size > MAX_IDENTIFIERS) {
             refinement.addIssue({
                 code: 'custom',
-                message: `\`pmcids\`, \`pmids\`, and \`dois\` together name ${distinct.size} distinct identifiers; a call accepts at most ${MAX_IDENTIFIERS} — split them across calls.`,
+                message: `\`pmcids\`, \`pmids\`, and \`dois\` together name ${distinct.size} distinct identifiers; a call accepts at most ${MAX_IDENTIFIERS} and fetches the first ${FETCH_LIMIT} — split them across calls.`,
             });
         }
     }),
     output: z.object({
-        articles: z.array(ArticleSchema).describe('Full-text articles'),
+        articles: z
+            .array(ArticleSchema)
+            .describe('Full-text articles in routing order — `pmcids`, then `pmids`, then `dois`, request order within each — each at the position of the id it would be deferred under, whichever tier served it. An article several ids name appears once.'),
         totalReturned: z
             .number()
             .describe('Number of articles in this response. Under a `maxResponseCharacters` budget this counts the kept articles only; `deferred.deferredCount` covers the rest.'),
         unavailable: z
             .array(UnavailableSchema)
             .optional()
-            .describe('Per-identifier explanations for any requested PMIDs, PMCIDs, or DOIs with no returnable full text. `idType` names the field each id was sent in. Distinct from `deferred`: nothing here is retrievable by re-calling, and an id never appears in both.'),
+            .describe('Per-identifier explanations for any requested PMIDs, PMCIDs, or DOIs with no returnable full text. `idType` names the field each id was sent in. Distinct from `deferred`: nothing here is retrievable by re-calling, and an id never appears in both. Ids past the per-call limit are listed in `overLimit`, never here.'),
         truncation: TruncationSchema.optional(),
         deferred: DeferredSchema.optional(),
+        overLimit: OverLimitSchema.optional(),
     }),
-    // Recovery guidance for five cases — a `sections` filter that removed every
-    // body section (#80), a record the chain could only retrieve as front matter
+    // Recovery guidance for six cases — a `sections` filter that removed every
+    // section (#80), a record the chain could only retrieve as front matter
     // (#86), a table returned with no cell values (#111), a body the per-article
-    // character budget shortened (#81), and articles the whole-response budget
-    // withheld (#100). Agent-facing context surfaced via
-    // ctx.enrich.notice() to structuredContent and content[]; absent when none
-    // applies.
+    // character budget shortened (#81), articles the whole-response budget
+    // withheld (#100), and identifiers past the per-call fetch limit (#222).
+    // Agent-facing context surfaced via ctx.enrich.notice() to structuredContent
+    // and content[]; absent when none applies.
     enrichment: {
         notice: z
             .string()
             .optional()
-            .describe('Optional guidance for a partial or empty body. A `sections`-filter miss names the requested terms and affected article id(s) and suggests retrying without `sections` or using broader headings. A metadata-only record names the id(s) the chain could retrieve as front matter only and points at `pubmed_fetch_articles` for the abstract. A table returned with no cell values names the affected table(s), the article each came from, and why the cells cannot be recovered. A budgeted response names the characters returned versus carried and points at `truncation`. A response-wide budget that deferred articles names the ids to re-request. Absent when none of those applies.'),
+            .describe('Optional guidance for a partial or empty body. A `sections`-filter miss names the requested terms and affected article id(s) and suggests retrying without `sections` or using broader headings. A metadata-only record names the id(s) the chain could retrieve as front matter only and points at `pubmed_fetch_articles` for the abstract. A table returned with no cell values names the affected table(s), the article each came from, and why the cells cannot be recovered. A budgeted response names the characters returned versus carried and points at `truncation`. A response-wide budget that deferred articles names the ids to re-request. Identifiers past the per-call limit are named with the field to resend each under. Absent when none of those applies.'),
         truncated: z
             .boolean()
             .optional()
-            .describe('True when a character budget shortened at least one returned body, or withheld a whole article. Absent when every resolved article is present with its full post-filter body. The per-article body accounting is in `truncation`; the withheld ids are in `deferred`.'),
+            .describe('True when a character budget shortened at least one returned body or withheld a whole article, or when the call named more distinct identifiers than one call fetches. Absent when every requested identifier was fetched and every resolved article is present with its full post-filter body. The per-article body accounting is in `truncation`; the withheld ids are in `deferred`; the unfetched ids are in `overLimit`.'),
     },
     async handler(input, ctx) {
         const idCount = (input.pmcids?.length ?? 0) + (input.pmids?.length ?? 0) + (input.dois?.length ?? 0);
@@ -1450,6 +1550,9 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             throw ctx.fail('blank_filter', `${sectionFilter.blank.map((path) => `\`${path}\``).join(', ')} ${one ? 'holds' : 'hold'} only whitespace or invisible characters, so ${one ? 'it names' : 'they name'} no section heading.`, { fields: sectionFilter.blank });
         }
         const filters = { ...input, sections: sectionFilter.terms };
+        // Settled before any upstream request: every tier below works the fetched
+        // ids alone, and the rest are handed back in `overLimit`. (#222)
+        const { fetched, overLimit: overLimitIds } = splitAtFetchLimit(input);
         // ── Chain tracking ──────────────────────────────────────────────────────
         // Per-input-id tier history (the `triedTiers` array on unavailable entries).
         // Keys: canonical PMID for a `pmids` entry, prefixed PMCID for a `pmcids`
@@ -1477,9 +1580,9 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // `dois` entry that named it — so a PMC miss can still reach Unpaywall
         // without another lookup, whichever field owns the record.
         const doiByPmcRecord = new Map();
-        // Ids of returned articles whose `sections` filter removed every body
-        // section — collected across the PMC and EPMC stages to drive one recovery
-        // notice via ctx.enrich.notice (#80).
+        // Ids of returned articles whose `sections` filter removed every section —
+        // collected across the PMC and EPMC stages to drive one recovery notice via
+        // ctx.enrich.notice (#80).
         const sectionFilterMisses = [];
         // Input ids whose PMC or EPMC record carried no body sections at all. Those
         // records are not full-text hits, so the chain continues past them; ids still
@@ -1574,7 +1677,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         };
         // `PMC123`, `pmc123`, `123` and `PMC0123` name one record; it runs the
         // chain once, keyed and reported in `PMC<digits>` form. (#170)
-        for (const id of input.pmcids ?? []) {
+        for (const id of fetched.pmcids) {
             const normalized = normalizePmcId(id);
             const key = withPmcPrefix(normalized);
             if (!chainByInput.has(key))
@@ -1585,9 +1688,9 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // The ID Converter parses `00000001` as PMID 1 yet reports it "not found
         // in PMC", and every later stage answers with NCBI's own PMID, so the chain
         // runs once per distinct PMID in its canonical form. (#161)
-        for (const id of input.pmids ?? [])
+        for (const id of fetched.pmids)
             addCallerId(normalizePmid(id), { id, idType: 'pmid' });
-        const pmids = [...new Set((input.pmids ?? []).map(normalizePmid))];
+        const pmids = [...new Set(fetched.pmids.map(normalizePmid))];
         // DOIs resolve through the converter too, so PMC-indexed DOIs reach PMC
         // EFetch instead of going straight to the EPMC/Unpaywall fallback (which
         // misses articles whose only OA copy is the PMC JATS).
@@ -1597,7 +1700,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // DOI shares one chain, keyed by the first spelling submitted, and
         // converter records are matched to it case-insensitively. (#166)
         const chainKeyByDoi = new Map();
-        for (const doi of input.dois ?? []) {
+        for (const doi of fetched.dois) {
             const key = chainKeyByDoi.get(doi.toLowerCase()) ?? doi;
             chainKeyByDoi.set(doi.toLowerCase(), key);
             addCallerId(key, { id: doi, idType: 'doi' });
@@ -1709,17 +1812,18 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 const bodylessPmcIds = new Set();
                 const parsed = [];
                 for (const node of findAll(articleSet, 'article')) {
-                    const before = parsePmcArticle(node);
-                    if (isBodylessArticle(before)) {
-                        if (before.pmcId)
-                            bodylessPmcIds.add(before.pmcId);
+                    const parsedArticle = parsePmcArticle(node);
+                    if (isBodylessArticle(parsedArticle)) {
+                        if (parsedArticle.pmcId)
+                            bodylessPmcIds.add(parsedArticle.pmcId);
                         continue;
                     }
+                    const before = withBackMatter(parsedArticle);
                     const after = applyPmcFilters(before, filters);
                     if (isSectionFilterMiss(before, after, filters.sections)) {
                         sectionFilterMisses.push(articleDisplayId(after));
                     }
-                    const budgeted = applyPmcBudget(after, budget);
+                    const budgeted = applyPmcBudget(after, budget, bodySectionCount(parsedArticle, filters));
                     omittedSections += budgeted.omittedSections;
                     if (budgeted.truncation) {
                         truncatedArticles.push({
@@ -1998,46 +2102,56 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 });
             }
         }
-        // Whole-response budget: fill with complete records in response order and
+        // Each article is handed back under the first spelling of the id that owns
+        // it, in the field that id was sent in. Every recovery site records the
+        // owner; a PMC record that came back without a PMC ID has none, and is
+        // reported under the id it carries — the total-function fallback, not an
+        // expected path.
+        const handBackId = (a) => {
+            const key = inputIdByArticle.get(a);
+            const owner = key === undefined ? undefined : callerIds.get(key)?.[0];
+            return (owner ?? { id: articleDisplayId(a), idType: a.pmcId ? 'pmcid' : a.pmid ? 'pmid' : 'doi' });
+        };
+        // Articles run in routing order, each at the position of the id it is
+        // handed back under: PMC EFetch answers in an order that is neither the
+        // request's nor stable between calls, and the tiers finish in tier order,
+        // so neither can decide what a budget keeps. An article with no owner sorts
+        // last; the sort is stable. (#235)
+        const routingPosition = new Map();
+        for (const [index, { key }] of requestedIds(fetched).entries()) {
+            if (!routingPosition.has(key))
+                routingPosition.set(key, index);
+        }
+        const positionOf = (a) => {
+            const { idType, id } = handBackId(a);
+            return routingPosition.get(requestKey(idType, id)) ?? routingPosition.size;
+        };
+        const resolved = [...pmcArticles, ...fallbackArticles]
+            .map((article) => ({ article, position: positionOf(article) }))
+            .sort((a, b) => a.position - b.position)
+            .map(({ article }) => article);
+        // Whole-response budget: fill with complete records in routing order and
         // hand the rest back as identifiers the caller can re-submit. One ledger for
         // every tier — a PMC-served article and an Unpaywall-served one spend the
-        // same characters. Without `maxResponseCharacters` nothing is measured and
-        // the response is exactly what it was before the budget existed. (#100)
-        const resolved = [...pmcArticles, ...fallbackArticles];
+        // same characters. Without `maxResponseCharacters` nothing is measured.
+        // (#100)
         const ceiling = input.maxResponseCharacters;
         const fit = ceiling === undefined ? undefined : fitWholeItems(resolved, ceiling);
         const articles = fit?.kept ?? resolved;
         const nextDeferredCharacters = fit?.nextDeferredCharacters;
-        // Each deferred article is handed back under the first spelling of the id
-        // that owns it, in the field that id was sent in. Every recovery site
-        // records the owner; a PMC record that came back without a PMC ID has none,
-        // and is reported under the id it carries — the total-function fallback,
-        // not an expected path.
-        const deferredIds = (fit?.deferred ?? []).map((a) => {
-            const key = inputIdByArticle.get(a);
-            const owner = key === undefined ? undefined : callerIds.get(key)?.[0];
-            return (owner ?? { id: articleDisplayId(a), idType: a.pmcId ? 'pmcid' : a.pmid ? 'pmid' : 'doi' });
-        });
-        const deferredFields = new Set(deferredIds.map((d) => d.idType));
-        const [onlyField] = deferredFields;
-        const deferredUnder = (idType) => deferredIds.filter((d) => d.idType === idType).map((d) => d.id);
+        const deferredIds = (fit?.deferred ?? []).map(handBackId);
         const deferred = ceiling !== undefined && nextDeferredCharacters !== undefined && fit
             ? {
                 maxResponseCharacters: ceiling,
                 returnedCharacters: fit.keptCharacters,
                 deferredCount: fit.deferred.length,
-                // One field names them all — always so for a single-field call — or
-                // each field's list says where to resend its ids. (#192)
-                ...(deferredFields.size === 1 && onlyField && { idType: onlyField }),
-                ids: deferredIds.map((d) => d.id),
-                ...(deferredFields.size > 1 && {
-                    ...(deferredFields.has('pmcid') && { pmcids: deferredUnder('pmcid') }),
-                    ...(deferredFields.has('pmid') && { pmids: deferredUnder('pmid') }),
-                    ...(deferredFields.has('doi') && { dois: deferredUnder('doi') }),
-                }),
+                ...groupIdsByField(deferredIds),
                 nextDeferredCharacters,
             }
             : undefined;
+        const overLimit = overLimitIds.length > 0
+            ? { limit: FETCH_LIMIT, ...groupIdsByField(overLimitIds) }
+            : undefined;
         // A deferred article takes its body accounting out of the response with it —
         // those counts describe text the caller never received.
         if (fit) {
@@ -2052,6 +2166,12 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 }
             }
         }
+        // The per-article ledgers fill as the tiers finish; listed in the returned
+        // articles' routing order so identical calls report them identically. (#235)
+        const articleRank = new Map(articles.map((a, i) => [articleDisplayId(a), i]));
+        const rankOf = (id) => articleRank.get(id) ?? articleRank.size;
+        truncatedArticles.sort((a, b) => rankOf(a.id) - rankOf(b.id));
+        sectionFilterMisses.sort((a, b) => rankOf(a) - rankOf(b));
         ctx.log.info('pubmed_fetch_fulltext completed', {
             requested: idCount,
             returned: articles.length,
@@ -2060,6 +2180,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             unpaywallHits: fallbackArticles.length,
             unavailable: unavailable.length,
             ...(deferred && { deferred: deferred.deferredCount }),
+            ...(overLimit && { overLimit: overLimit.ids.length }),
         });
         // Summed off the per-article entries rather than carried through every
         // stage, so a deferred article's dropped tables leave the roll-up together
@@ -2102,7 +2223,17 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             ctx.enrich({ truncated: true });
         }
         if (deferred) {
-            notices.push(buildDeferralNotice(deferred));
+            notices.push(buildDeferralNotice(deferred, {
+                noun: 'article',
+                ids: deferred.ids.join(', '),
+                recall: deferred.idType
+                    ? `pubmed_fetch_fulltext with those ids under \`${deferred.idType}s\``
+                    : `pubmed_fetch_fulltext with each id under its own field (${idFieldLists(deferred)})`,
+            }));
+            ctx.enrich({ truncated: true });
+        }
+        if (overLimit) {
+            notices.push(buildOverLimitNotice(overLimit));
             ctx.enrich({ truncated: true });
         }
         if (notices.length > 0)
@@ -2113,6 +2244,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             ...(unavailable.length > 0 && { unavailable }),
             ...(truncation && { truncation }),
             ...(deferred && { deferred }),
+            ...(overLimit && { overLimit }),
         };
     },
     format: (result) => {
@@ -2143,16 +2275,11 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         }
         if (result.deferred) {
             const d = result.deferred;
-            lines.push(`\n**Deferred by the response budget:** ${d.deferredCount} article(s) — ${d.returnedCharacters} of ${d.maxResponseCharacters} budgeted characters returned; next deferred article ${d.nextDeferredCharacters} characters`);
-            // Rendered on presence, each independently: a response carries `idType`
-            // or the per-field lists, never both.
-            if (d.idType) {
-                lines.push(`Re-call \`pubmed_fetch_fulltext\` with these ${d.idType} ids as \`${d.idType}s\`: ${d.ids.join(', ')}`);
-            }
-            const fieldLists = deferredFieldLists(d);
-            if (fieldLists) {
-                lines.push(`Re-call \`pubmed_fetch_fulltext\` with these ids, each under its own field — ${fieldLists}`);
-            }
+            lines.push(`\n**Deferred by the response budget:** ${d.deferredCount} article(s) — ${d.returnedCharacters} of ${d.maxResponseCharacters} budgeted characters returned; next deferred article ${d.nextDeferredCharacters} characters`, ...resendLines(d));
+        }
+        if (result.overLimit) {
+            const o = result.overLimit;
+            lines.push(`\n**Over the per-call limit:** ${o.ids.length} identifier(s) not fetched — a call fetches the first ${o.limit} distinct identifiers`, ...resendLines(o));
         }
         // An empty response under a budget is a deferral, not an absence — the
         // articles resolved and the ids above retrieve them.
@@ -2173,6 +2300,93 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         return [{ type: 'text', text: lines.join('\n') }];
     },
 });
+/**
+ * Every requested id in routing order — `pmcids`, then `pmids`, then `dois`,
+ * request order within each — as sent. Every spelling one field accepts for an
+ * identifier shares a key, and the same digits in two fields are two keys.
+ * (#192, #222)
+ */
+function requestedIds(fields) {
+    const inField = (idType, ids) => (ids ?? []).map((id) => ({ id, idType, key: requestKey(idType, id) }));
+    return [
+        ...inField('pmcid', fields.pmcids),
+        ...inField('pmid', fields.pmids),
+        ...inField('doi', fields.dois),
+    ];
+}
+/** The key {@link requestedIds} gives an id sent in `idType`'s field. */
+function requestKey(idType, id) {
+    switch (idType) {
+        case 'pmcid':
+            return `pmcid:${normalizePmcId(id)}`;
+        case 'pmid':
+            return `pmid:${normalizePmid(id)}`;
+        case 'doi':
+            return `doi:${id.toLowerCase()}`;
+    }
+}
+/**
+ * Split the requested ids at the per-call fetch limit, before any upstream
+ * request. The first {@link FETCH_LIMIT} distinct identifiers in routing order
+ * are fetched, each with every spelling that names it; each later identifier is
+ * handed back once, under its first spelling — a PMC ID in the `PMC<digits>`
+ * form every output reports it in. (#222)
+ */
+function splitAtFetchLimit(fields) {
+    const fetched = { pmcids: [], pmids: [], dois: [] };
+    const overLimit = [];
+    const admitted = new Set();
+    const listed = new Set();
+    for (const { id, idType, key } of requestedIds(fields)) {
+        if (admitted.has(key) || admitted.size < FETCH_LIMIT) {
+            admitted.add(key);
+            fetched[`${idType}s`].push(id);
+        }
+        else if (!listed.has(key)) {
+            listed.add(key);
+            overLimit.push({ id: idType === 'pmcid' ? withPmcPrefix(normalizePmcId(id)) : id, idType });
+        }
+    }
+    return { fetched, overLimit };
+}
+/**
+ * Group ids handed back for a follow-up call: one field names them all —
+ * always so for a single-field call — or each field's list says where to
+ * resend its ids. (#192, #222)
+ */
+function groupIdsByField(callerIds) {
+    const fields = new Set(callerIds.map((c) => c.idType));
+    const [onlyField] = fields;
+    const under = (idType) => callerIds.filter((c) => c.idType === idType).map((c) => c.id);
+    return {
+        ...(fields.size === 1 && onlyField && { idType: onlyField }),
+        ids: callerIds.map((c) => c.id),
+        ...(fields.size > 1 && {
+            ...(fields.has('pmcid') && { pmcids: under('pmcid') }),
+            ...(fields.has('pmid') && { pmids: under('pmid') }),
+            ...(fields.has('doi') && { dois: under('doi') }),
+        }),
+    };
+}
+/**
+ * The `content[]` lines that resend a group of ids. Rendered on presence, each
+ * independently: a group carries `idType` or the per-field lists, never both.
+ */
+function resendLines(group) {
+    const fieldLists = idFieldLists(group);
+    return [
+        ...(group.idType
+            ? [
+                `Re-call \`pubmed_fetch_fulltext\` with these ${group.idType} ids as \`${group.idType}s\`: ${group.ids.join(', ')}`,
+            ]
+            : []),
+        ...(fieldLists
+            ? [
+                `Re-call \`pubmed_fetch_fulltext\` with these ids, each under its own field — ${fieldLists}`,
+            ]
+            : []),
+    ];
+}
 /**
  * Merge what a Europe PMC hit carried onto a candidate bound for Unpaywall. A
  * DOI the candidate already holds wins — for a `dois` entry it is the caller's
@@ -2373,16 +2587,17 @@ async function fetchEpmcArticle(epmc, hit, args, contextPmid) {
         if (!articleNode) {
             return { kind: 'no-fulltext', detail: 'EPMC fullTextXML payload had no <article> element' };
         }
-        const beforeFilter = parsePmcArticle(articleNode);
-        if (isBodylessArticle(beforeFilter)) {
+        const parsedArticle = parsePmcArticle(articleNode);
+        if (isBodylessArticle(parsedArticle)) {
             return {
                 kind: 'no-body',
                 detail: 'EPMC fullTextXML carried front matter and abstract only, with no body sections',
             };
         }
+        const beforeFilter = withBackMatter(parsedArticle);
         const parsed = applyPmcFilters(beforeFilter, args.input);
         const sectionFilterMiss = isSectionFilterMiss(beforeFilter, parsed, args.input.sections);
-        const budgeted = applyPmcBudget(parsed, args.budget);
+        const budgeted = applyPmcBudget(parsed, args.budget, bodySectionCount(parsedArticle, args.input));
         // `parsePmcArticle` always returns string fields (sometimes empty). Strip
         // empty `pmcId`/`pmcUrl` for EPMC-only records (preprints) so the schema's
         // optional shape is respected — agents read `epmcId`/`epmcSource` for those.
@@ -2807,7 +3022,11 @@ function formatPmcArticle(a, lines, truncation, mode) {
         lines.push(`**Type:** ${a.articleType}`);
     if (a.publicationDate) {
         const d = a.publicationDate;
-        const dateParts = [d.year, d.month, d.day].filter(Boolean);
+        // JATS deposits often write `<month>7</month>`; the rendered date pads a
+        // one-digit numeric month or day so it reads as ISO, while the structured
+        // parts stay as deposited. A named month (`Jul`) passes through. (#242)
+        const pad = (part) => (part && /^\d$/.test(part) ? `0${part}` : part);
+        const dateParts = [d.year, pad(d.month), pad(d.day)].filter(Boolean);
         if (dateParts.length)
             lines.push(`**Published:** ${dateParts.join('-')}`);
     }
@@ -2913,7 +3132,7 @@ function formatAssets(assets, lines) {
     lines.push(`\n#### Assets (${assets.length})`);
     lines.push(`\n> \`file\` is the pointer exactly as deposited — a name inside the PMC deposit, not a fetchable URL. Open the article at the PMC link above to view it.`);
     for (const asset of assets) {
-        const heading = [asset.label, asset.caption].filter(Boolean).join(' — ');
+        const heading = [assetLabelName(asset), asset.caption].filter(Boolean).join(' — ');
         lines.push(`\n##### ${escapeMarkdownInline(heading || 'Asset')}`);
         const meta = [
             asset.assetType,
@@ -3009,7 +3228,7 @@ function formatPmcAuthor(au) {
     const parts = [];
     if (au.collectiveName)
         parts.push(`${au.collectiveName} (collective)`);
-    const name = [au.givenNames, au.lastName].filter(Boolean).join(' ');
+    const name = [au.givenNames, au.lastName, au.suffix].filter(Boolean).join(' ');
     if (name)
         parts.push(name);
     return parts.join(' — ') || 'Unknown';
@@ -3033,7 +3252,7 @@ function sectionHeading(section) {
     return section.label ? escapeMarkdownInline(section.label) : UNTITLED_SECTION_LABEL;
 }
 /**
- * Render one body section and everything nested under it, one markdown heading
+ * Render one section and everything nested under it, one markdown heading
  * level per nesting level. Walks the full depth the output schema carries, so
  * `content[]` shows every section `structuredContent` does. Headings stop
  * deepening at `######`, the deepest markdown supports. (#112)