@cyanheads/pubmed-mcp-server 2.10.6 → 2.10.8

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

@@ -28,6 +28,7 @@ import { parsePmcArticle } from '../../../services/ncbi/parsing/pmc-article-pars
 import { findAll, findOne } from '../../../services/ncbi/parsing/pmc-xml-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 { conceptMeta, EDAM_DATA_RETRIEVAL, SCHEMA_SCHOLARLY_ARTICLE } from './_concepts.js';
 import { pmidStringSchema } from './_schemas.js';
 import { escapeMarkdownInline, sliceCodeUnits } from './_text.js';
@@ -41,6 +42,43 @@ function filterSections(sections, sectionFilter) {
     const lowerFilter = sectionFilter.map((s) => s.toLowerCase());
     return sections.filter((s) => s.title && lowerFilter.some((f) => s.title?.toLowerCase().includes(f)));
 }
+/**
+ * Render a section subtree as text blocks, in document order: each section's
+ * heading on its own line above its text. Used for the levels past
+ * {@link MAX_SECTION_DEPTH}, which have no node of their own to live in. (#112)
+ */
+function flattenSectionText(section) {
+    const heading = section.title ? formatHeading(section.label, section.title) : undefined;
+    const block = [heading, section.text].filter(Boolean).join('\n');
+    return [...(block ? [block] : []), ...(section.subsections ?? []).flatMap(flattenSectionText)];
+}
+/**
+ * Clamp a section tree to the depth the output schema declares. A section at the
+ * deepest level absorbs its descendants into its own text instead of carrying
+ * them as subsections the schema would strip on validation — silently, from both
+ * `structuredContent` and `content[]`. Shallower trees pass through untouched.
+ * (#112)
+ */
+function clampSectionDepth(sections, depth = 1) {
+    return sections.map((section) => {
+        const subsections = section.subsections;
+        if (!subsections?.length)
+            return section;
+        if (depth < MAX_SECTION_DEPTH) {
+            return { ...section, subsections: clampSectionDepth(subsections, depth + 1) };
+        }
+        const { subsections: _dropped, ...rest } = section;
+        const tail = subsections.flatMap(flattenSectionText);
+        return { ...rest, text: [section.text, ...tail].filter(Boolean).join('\n\n') };
+    });
+}
+/**
+ * Apply the requested section/reference filters, then clamp the section tree to
+ * the depth the output schema carries. Both run here so every path producing a
+ * `pmc` article — PMC EFetch and the Europe PMC stage — shares one shape, and
+ * the budget helpers downstream count the text that will actually survive
+ * validation. (#112)
+ */
 function applyPmcFilters(article, filters) {
     let out = article;
     if (filters.sections?.length) {
@@ -53,7 +91,7 @@ function applyPmcFilters(article, filters) {
         const { references: _, ...rest } = out;
         out = rest;
     }
-    return out;
+    return { ...out, sections: clampSectionDepth(out.sections) };
 }
 /**
  * True when a `sections` filter removed every body section from an article that
@@ -109,11 +147,30 @@ function buildBodylessNotice(affectedIds) {
     return `No body text could be retrieved for ${subject} — the full-text source returned front matter and abstract only, and no later tier recovered a copy. See \`triedTiers\` on the \`unavailable\` entry for what each tier reported, and use \`pubmed_fetch_articles\` for the abstract and metadata.`;
 }
 // ─── Schemas ─────────────────────────────────────────────────────────────────
+/**
+ * How many `<sec>` levels the output schema carries as structured nodes. JATS
+ * nesting is unbounded and the parser recurses without a cap, so the schema is
+ * what decides how deep a section survives output validation — anything past it
+ * used to be dropped silently from both output surfaces (#112). Sections deeper
+ * than this are now flattened into the deepest surviving node's text instead, so
+ * no body content is lost at any depth.
+ *
+ * Two is the ceiling the tool's own contract can verify, not a guess at how deep
+ * real records nest: `format-parity`'s sentinel walker stops after 8 schema hops,
+ * and `articles[]` → the article union → `sections[]` → `subsections[]` already
+ * spends them all. A third `subsections` level puts its own elements out of the
+ * walker's reach, so `format()` parity for that subtree would ship unverified.
+ * Levels are inlined rather than expressed with `z.lazy()` regardless — a
+ * self-referential schema emits `$defs`/`$ref`, which Gemini rejects.
+ */
+const MAX_SECTION_DEPTH = 2;
 const SubsectionSchema = z
     .object({
     title: z.string().optional().describe('Subsection heading'),
     label: z.string().optional().describe('Subsection label'),
-    text: z.string().describe('Subsection body text'),
+    text: z
+        .string()
+        .describe('Subsection body text. Sections nested deeper than this level are folded in here in document order, each heading rendered on its own line above its text.'),
 })
     .describe('Article subsection');
 const SectionSchema = z
@@ -251,7 +308,10 @@ const UnavailableReasonSchema = z
     'parse-failed',
     'service-error',
 ])
-    .describe('Why no full text was returned. not-found: upstream returned no record for this ID. no-pmc-fallback-disabled: every tier was skipped (`triedTiers` is all `not-attempted`) — typically because EPMC (`EUROPEPMC_ENABLED`) and Unpaywall (`UNPAYWALL_EMAIL`) are not configured. no-epmc-fulltext: EPMC indexed the record but publishes no fullTextXML. no-body: the record was retrieved but carries front matter and abstract only, with no body sections — use `pubmed_fetch_articles` for the metadata. no-doi: no DOI to query Unpaywall. no-oa: Unpaywall has no OA copy. fetch-failed: download failed. parse-failed: extraction empty. service-error: upstream server failure (threw, timed out, or returned malformed data).');
+    .describe('Why no full text was returned — the most specific signal any tier that answered reported. not-found: upstream returned no record for this ID. no-pmc-fallback-disabled: every tier was skipped (`triedTiers` is all `not-attempted`) — typically because EPMC (`EUROPEPMC_ENABLED`) and Unpaywall (`UNPAYWALL_EMAIL`) are not configured. no-epmc-fulltext: EPMC indexed the record but publishes no fullTextXML. no-body: the record was retrieved but carries front matter and abstract only, with no body sections — use `pubmed_fetch_articles` for the metadata. no-doi: no DOI to query Unpaywall. no-oa: Unpaywall has no OA copy. fetch-failed: download failed. parse-failed: extraction empty. service-error: upstream server failure (threw, timed out, or returned malformed data). A reason never means the chain ran to completion — read `unqueriedTiers` for that.');
+const UnqueriedTierSchema = z
+    .enum(['europepmc', 'unpaywall'])
+    .describe('A fallback tier this deployment has not configured');
 const TierOutcomeSchema = z
     .enum([
     'not-attempted',
@@ -282,6 +342,10 @@ const UnavailableSchema = z
     triedTiers: z
         .array(TriedTierSchema)
         .describe('Per-tier outcomes the chain produced for this id, in execution order. Covers `pmc`, `europepmc`, and `unpaywall` — the same tiers the tool description references. Tiers that the chain skipped appear as `outcome: not-attempted` with a `detail` explaining why.'),
+    unqueriedTiers: z
+        .array(UnqueriedTierSchema)
+        .optional()
+        .describe('Tiers the chain skipped because this deployment has not configured them, and that could have served this id — the search was incomplete, and a deployment with these tiers configured may still resolve the id. `triedTiers` carries which environment variable each one is waiting on. Absent when every tier that could have served the id was actually queried; a tier skipped because it was inapplicable to this id (no DOI for Unpaywall) is never listed.'),
 })
     .describe('One identifier that could not be returned, with the full chain it traversed');
 // ─── Character-budget schemas ────────────────────────────────────────────────
@@ -341,14 +405,55 @@ const TruncationSchema = z
         .describe('Per-article accounting, covering only the articles the budget shortened'),
 })
     .describe('Character accounting for full text the budget shortened. Present only when a budget actually removed characters — its absence means every returned article carries its full post-filter body.');
+const DeferredSchema = z
+    .object({
+    maxResponseCharacters: z
+        .number()
+        .describe('The `maxResponseCharacters` ceiling this response was budgeted against'),
+    returnedCharacters: z
+        .number()
+        .describe('Serialized characters the returned article records account for'),
+    deferredCount: z
+        .number()
+        .describe('Articles the chain resolved but withheld to stay under the ceiling'),
+    idType: z
+        .enum(['pmid', 'pmcid', 'doi'])
+        .describe('Which input branch the deferred ids belong to — re-submit them as `pmids`, `pmcids`, or `dois` respectively. Matches the `idType` on `unavailable` entries.'),
+    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` branch and the same other inputs. Never contains an id from `unavailable`.'),
+    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('Continuation state for articles the whole-response budget withheld. Present only when `maxResponseCharacters` deferred at least one article.');
 /** 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) {
     return budget.maxCharacters !== undefined || budget.maxCharactersPerSection !== undefined;
 }
-/** Body characters a top-level section carries — its own text plus its subsections'. */
+/** Every text field in a section subtree, in document order, own text first. */
+function sectionTextFields(section) {
+    return [section.text, ...(section.subsections ?? []).flatMap(sectionTextFields)];
+}
+/**
+ * Body characters a section carries — its own text plus every nested
+ * subsection's. Measured off {@link sectionTextFields} rather than its own walk,
+ * so the count the budget reports as `originalCharacters` is always taken over
+ * exactly the fields {@link fitFields} shortens.
+ */
 function sectionCharacters(section) {
-    return (section.text.length + (section.subsections?.reduce((n, sub) => n + sub.text.length, 0) ?? 0));
+    return sectionTextFields(section).reduce((n, text) => n + text.length, 0);
+}
+/**
+ * Rebuild a section subtree from `fitted`, consuming one entry per node in the
+ * same document order {@link sectionTextFields} produced them. `cursor` walks
+ * the flat list across the whole subtree.
+ */
+function withFittedTexts(section, fitted, cursor) {
+    const text = fitted[cursor.i++] ?? '';
+    const subsections = section.subsections?.map((sub) => withFittedTexts(sub, fitted, cursor));
+    return { ...section, text, ...(subsections && { subsections }) };
 }
 /**
  * Shorten an ordered list of text fields so their combined length fits
@@ -448,7 +553,7 @@ function applyPmcBudget(article, budget) {
     let returnedCharacters = 0;
     article.sections.forEach((section, i) => {
         const original = sizes[i] ?? 0;
-        const fitted = fitFields([section.text, ...(section.subsections?.map((sub) => sub.text) ?? [])], allowances[i] ?? 0);
+        const fitted = fitFields(sectionTextFields(section), allowances[i] ?? 0);
         const returned = fitted.reduce((sum, text) => sum + text.length, 0);
         returnedCharacters += returned;
         sectionReports.push({
@@ -461,13 +566,7 @@ function applyPmcBudget(article, budget) {
             omittedSections += 1;
             return;
         }
-        kept.push({
-            ...section,
-            text: fitted[0] ?? '',
-            ...(section.subsections && {
-                subsections: section.subsections.map((sub, j) => ({ ...sub, text: fitted[j + 1] ?? '' })),
-            }),
-        });
+        kept.push(withFittedTexts(section, fitted, { i: 0 }));
     });
     if (returnedCharacters === originalCharacters && omittedSections === 0) {
         return { article, omittedSections: 0 };
@@ -512,6 +611,29 @@ function buildTruncationNotice(truncation) {
     ].filter((k) => k !== undefined);
     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} 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)
+ */
+function buildDeferralNotice(deferred) {
+    const spent = deferred.returnedCharacters === 0
+        ? `No article fits the requested maxResponseCharacters of ${deferred.maxResponseCharacters}, so none were returned.`
+        : `Response character budget reached: ${deferred.returnedCharacters} of ${deferred.maxResponseCharacters} characters returned.`;
+    return `${spent} ${deferred.deferredCount} resolved article(s) were deferred whole: ${deferred.ids.join(', ')}. Re-call pubmed_fetch_fulltext with those ids under \`${deferred.idType}s\` to retrieve them, or raise maxResponseCharacters to at least ${deferred.nextDeferredCharacters} — the size of the next deferred article.`;
+}
+/**
+ * Body sections an article's per-article budget dropped, derived from that
+ * article's own accounting by the rule {@link applyPmcBudget} counts by:
+ * `outline` mode keeps every heading, so it drops none. Used to take a deferred
+ * article's contribution back out of the response-level roll-up. (#100)
+ */
+function countOmittedSections(entry, mode) {
+    if (mode !== 'truncate')
+        return 0;
+    return (entry.sections ?? []).filter((s) => s.originalCharacters > 0 && s.returnedCharacters === 0).length;
+}
 // ─── Tool Definition ─────────────────────────────────────────────────────────
 /**
  * Compose the tool description for the fallback tiers enabled in this
@@ -546,7 +668,8 @@ export function buildFulltextDescription(tiers) {
                 ? '; DOIs with no PMC copy recover via Unpaywall open access'
                 : '';
     const input = `Provide exactly one of \`pmcids\` (PMC IDs directly), \`pmids\` (PubMed IDs, auto-resolved), or \`dois\` (DOIs, auto-resolved to PMC via the ID Converter${doiTail}).`;
-    return `${base} ${fallback} ${input}`;
+    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();
 export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
@@ -605,7 +728,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             .min(1)
             .max(1_000_000)
             .optional()
-            .describe('Per-article budget for body text, in characters. Counts `source=pmc` section and subsection text, or the `source=unpaywall` `content` body; titles, abstracts, identifiers, and references are never counted or shortened. Applied after `sections`, `maxSections`, and `includeReferences`, so semantic filtering is unaffected. The response-wide ceiling is this value times the number of articles returned. Omit for the full body.'),
+            .describe('Per-article budget for body text, in characters. Counts `source=pmc` section and subsection text, or the `source=unpaywall` `content` body; titles, abstracts, identifiers, and references are never counted or shortened. Applied after `sections`, `maxSections`, and `includeReferences`, 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()
@@ -613,6 +736,13 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             .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.'),
+        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.'),
         overflowMode: z
             .enum(['truncate', 'outline'])
             .default('truncate')
@@ -623,27 +753,31 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
     }),
     output: z.object({
         articles: z.array(ArticleSchema).describe('Full-text articles'),
-        totalReturned: z.number().describe('Number of articles returned'),
+        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` discriminates which branch the id came from.'),
+            .describe('Per-identifier explanations for any requested PMIDs, PMCIDs, or DOIs with no returnable full text. `idType` discriminates which branch the id came from. Distinct from `deferred`: nothing here is retrievable by re-calling, and an id never appears in both.'),
         truncation: TruncationSchema.optional(),
+        deferred: DeferredSchema.optional(),
     }),
-    // Recovery guidance for three cases — a `sections` filter that removed every
+    // Recovery guidance for four cases — a `sections` filter that removed every
     // body section (#80), a record the chain could only retrieve as front matter
-    // (#86), and a body the character budget shortened (#81). Agent-facing context
-    // surfaced via ctx.enrich.notice() to structuredContent and content[]; absent
-    // when none applies.
+    // (#86), 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.
     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 budgeted response names the characters returned versus carried and points at `truncation`. 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 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.'),
         truncated: z
             .boolean()
             .optional()
-            .describe('True when a character budget shortened at least one returned body. Absent when every returned article carries its full post-filter body. The per-article accounting is in `truncation`.'),
+            .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`.'),
     },
     async handler(input, ctx) {
         ctx.log.info('Executing pubmed_fetch_fulltext', {
@@ -659,6 +793,17 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // for, so we can skip them when building `unavailable[]`.
         const chainByInput = new Map();
         const recoveredIds = new Set();
+        // Per-input-id set of tiers this deployment has not configured AND that
+        // could have served that id — the `unqueriedTiers` array on unavailable
+        // entries. Insertion order is chain order, so the array reads in the order
+        // the tiers would have run. A tier skipped as inapplicable is never marked;
+        // that is a settled answer, not an incomplete search. (#110)
+        const unqueriedByInput = new Map();
+        const markUnqueried = (inputId, tier) => {
+            const tiers = unqueriedByInput.get(inputId) ?? new Set();
+            tiers.add(tier);
+            unqueriedByInput.set(inputId, tiers);
+        };
         // Back-map from a converter-resolved prefixed PMCID to the input id that
         // seeded it — a PMID for `pmids` input, a DOI for `dois` input — so the PMC
         // and EPMC stages attribute recoveries and misses to the original input id.
@@ -679,6 +824,11 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // requested or nothing exceeded it (#81).
         const truncatedArticles = [];
         let omittedSections = 0;
+        // The input id each returned article was requested under, so the
+        // whole-response budget can hand deferred articles back as identifiers the
+        // caller can re-submit rather than whatever id the article happens to
+        // carry — a `pmids` request recovers articles keyed by PMCID. (#100)
+        const inputIdByArticle = new Map();
         const budget = {
             overflowMode: input.overflowMode,
             ...(input.maxCharacters !== undefined && { maxCharacters: input.maxCharacters }),
@@ -843,7 +993,15 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                             ...budgeted.truncation,
                         });
                     }
-                    parsed.push({ source: 'pmc', viaSource: 'pmc', ...budgeted.article });
+                    const article = {
+                        source: 'pmc',
+                        viaSource: 'pmc',
+                        ...budgeted.article,
+                    };
+                    parsed.push(article);
+                    if (article.pmcId) {
+                        inputIdByArticle.set(article, pmcidToInputId.get(article.pmcId) ?? article.pmcId);
+                    }
                 }
                 pmcArticles = parsed;
                 const returnedPmcIds = new Set(pmcArticles.map((a) => a.pmcId).filter((id) => !!id));
@@ -905,10 +1063,14 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 sectionFilterMisses: [],
                 truncatedArticles: [],
                 omittedSections: 0,
+                articleInputIds: new Map(),
             };
         pmcArticles = pmcArticles.concat(epmcOutcomes.articles);
         truncatedArticles.push(...epmcOutcomes.truncatedArticles);
         omittedSections += epmcOutcomes.omittedSections;
+        for (const [article, candidateId] of epmcOutcomes.articleInputIds) {
+            inputIdByArticle.set(article, pmcidToInputId.get(candidateId) ?? candidateId);
+        }
         // Fold EPMC outcomes into each id's chain. EPMC-served articles count as
         // recovered, so their ids are added to `recoveredIds` here.
         if (!epmc) {
@@ -917,14 +1079,20 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 outcome: 'not-attempted',
                 detail: 'EUROPEPMC_ENABLED=false',
             };
+            // EPMC searches by PMID, PMCID, and DOI alike, so it could have served
+            // every candidate that reached this stage — no applicability test.
+            const skipEpmc = (inputId) => {
+                chainByInput.get(inputId)?.push(epmcDisabledEntry);
+                markUnqueried(inputId, 'europepmc');
+            };
             for (const c of pmidFallbackCandidates)
-                chainByInput.get(c.pmid)?.push(epmcDisabledEntry);
+                skipEpmc(c.pmid);
             for (const c of pmcidFallbackCandidates) {
                 const prefixed = withPmcPrefix(c.pmcid);
-                chainByInput.get(pmcidToInputId.get(prefixed) ?? prefixed)?.push(epmcDisabledEntry);
+                skipEpmc(pmcidToInputId.get(prefixed) ?? prefixed);
             }
             for (const c of doiCandidates)
-                chainByInput.get(c.doi)?.push(epmcDisabledEntry);
+                skipEpmc(c.doi);
         }
         else {
             const foldEpmcOutcome = (inputId, outcome) => {
@@ -957,13 +1125,19 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // Converter, which returns DOIs for PMC-indexed records. (#88)
         if (pmcidFallbackCandidates.length > 0) {
             if (!unpaywall) {
+                // The PMCID → DOI lookup below only runs when Unpaywall is configured,
+                // so a candidate arrives here with a DOI only if the EPMC stage handed
+                // one over. An absent DOI therefore means "never looked up", not "this
+                // record has none" — the tier stays a genuine unknown and is marked.
                 for (const c of pmcidFallbackCandidates) {
                     const prefixed = withPmcPrefix(c.pmcid);
-                    chainByInput.get(pmcidToInputId.get(prefixed) ?? prefixed)?.push({
+                    const inputId = pmcidToInputId.get(prefixed) ?? prefixed;
+                    chainByInput.get(inputId)?.push({
                         tier: 'unpaywall',
                         outcome: 'not-attempted',
                         detail: 'UNPAYWALL_EMAIL is not set',
                     });
+                    markUnqueried(inputId, 'unpaywall');
                 }
             }
             else {
@@ -1009,6 +1183,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                     const inputId = pmcidToInputId.get(pmcId) ?? pmcId;
                     if ('article' in result) {
                         fallbackArticles.push(result.article);
+                        inputIdByArticle.set(result.article, inputId);
                         if (result.truncation)
                             truncatedArticles.push(result.truncation);
                         recoveredIds.add(inputId);
@@ -1047,12 +1222,20 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 }
             }
             if (!unpaywall) {
+                // `fetchPubmedDois` has already run, so the DOI state is settled here.
+                // A candidate with no DOI could not have reached Unpaywall configured
+                // or not — that is `no-doi`, a real answer, not an incomplete search.
                 for (const c of pmidFallbackCandidates) {
+                    if (!c.doi) {
+                        chainByInput.get(c.pmid)?.push({ tier: 'unpaywall', outcome: 'no-doi' });
+                        continue;
+                    }
                     chainByInput.get(c.pmid)?.push({
                         tier: 'unpaywall',
                         outcome: 'not-attempted',
                         detail: 'UNPAYWALL_EMAIL is not set',
                     });
+                    markUnqueried(c.pmid, 'unpaywall');
                 }
             }
             else {
@@ -1065,6 +1248,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 for (const { candidate, result } of outcomes) {
                     if ('article' in result) {
                         fallbackArticles.push(result.article);
+                        inputIdByArticle.set(result.article, candidate.pmid);
                         if (result.truncation)
                             truncatedArticles.push(result.truncation);
                         recoveredIds.add(candidate.pmid);
@@ -1082,12 +1266,15 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         }
         if (doiCandidates.length > 0) {
             if (!unpaywall) {
+                // Every candidate on this branch is a DOI, so Unpaywall applies to all
+                // of them.
                 for (const c of doiCandidates) {
                     chainByInput.get(c.doi)?.push({
                         tier: 'unpaywall',
                         outcome: 'not-attempted',
                         detail: 'UNPAYWALL_EMAIL is not set',
                     });
+                    markUnqueried(c.doi, 'unpaywall');
                 }
             }
             else {
@@ -1100,6 +1287,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 for (const { doi, result } of outcomes) {
                     if ('article' in result) {
                         fallbackArticles.push(result.article);
+                        inputIdByArticle.set(result.article, doi);
                         if (result.truncation)
                             truncatedArticles.push(result.truncation);
                         recoveredIds.add(doi);
@@ -1120,14 +1308,50 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         for (const [id, chain] of chainByInput) {
             if (recoveredIds.has(id))
                 continue;
+            const unqueried = unqueriedByInput.get(id);
             unavailable.push({
                 id,
                 idType,
                 reason: reasonFromChain(chain),
                 triedTiers: chain,
+                ...(unqueried?.size && { unqueriedTiers: [...unqueried] }),
             });
         }
-        const articles = [...pmcArticles, ...fallbackArticles];
+        // Whole-response budget: fill with complete records in response 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];
+        const ceiling = input.maxResponseCharacters;
+        const fit = ceiling === undefined ? undefined : fitWholeItems(resolved, ceiling);
+        const articles = fit?.kept ?? resolved;
+        const nextDeferredCharacters = fit?.nextDeferredCharacters;
+        const deferred = ceiling !== undefined && nextDeferredCharacters !== undefined && fit
+            ? {
+                maxResponseCharacters: ceiling,
+                returnedCharacters: fit.keptCharacters,
+                deferredCount: fit.deferred.length,
+                idType,
+                // Every recovery site records the input id; `articleDisplayId` is
+                // the total-function fallback, not an expected path.
+                ids: fit.deferred.map((a) => inputIdByArticle.get(a) ?? articleDisplayId(a)),
+                nextDeferredCharacters,
+            }
+            : undefined;
+        // A deferred article takes its body accounting out of the response with it —
+        // those counts describe text the caller never received.
+        if (fit) {
+            for (const article of fit.deferred) {
+                const id = articleDisplayId(article);
+                const index = truncatedArticles.findIndex((t) => t.id === id);
+                if (index === -1)
+                    continue;
+                const [dropped] = truncatedArticles.splice(index, 1);
+                if (dropped)
+                    omittedSections -= countOmittedSections(dropped, input.overflowMode);
+            }
+        }
         ctx.log.info('pubmed_fetch_fulltext completed', {
             requested: (input.pmids ?? input.pmcids ?? input.dois)?.length ?? 0,
             returned: articles.length,
@@ -1135,6 +1359,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             epmcHits: pmcArticles.filter((a) => a.viaSource === 'europepmc').length,
             unpaywallHits: fallbackArticles.length,
             unavailable: unavailable.length,
+            ...(deferred && { deferred: deferred.deferredCount }),
         });
         // Rolled up only when the budget actually removed characters, so an
         // under-budget request returns exactly what it did before the budget
@@ -1165,6 +1390,10 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             notices.push(buildTruncationNotice(truncation));
             ctx.enrich({ truncated: true });
         }
+        if (deferred) {
+            notices.push(buildDeferralNotice(deferred));
+            ctx.enrich({ truncated: true });
+        }
         if (notices.length > 0)
             ctx.enrich.notice(notices.join(' '));
         return {
@@ -1172,14 +1401,20 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             totalReturned: articles.length,
             ...(unavailable.length > 0 && { unavailable }),
             ...(truncation && { truncation }),
+            ...(deferred && { deferred }),
         };
     },
     format: (result) => {
         const lines = [`## Full-Text Articles`, `**Articles Returned:** ${result.totalReturned}`];
         if (result.unavailable?.length) {
             lines.push(`\n**Unavailable (${result.unavailable.length}):**`);
+            let anyUnqueried = false;
             for (const u of result.unavailable) {
                 lines.push(`- [${u.idType}] ${u.id} — ${u.reason}`);
+                if (u.unqueriedTiers?.length) {
+                    anyUnqueried = true;
+                    lines.push(`  Not queried: ${formatUnqueriedTiers(u.unqueriedTiers, u.triedTiers)}`);
+                }
                 const chain = u.triedTiers
                     .map((t) => {
                     const detail = t.detail ? sanitizeChainDetail(t.detail) : undefined;
@@ -1189,8 +1424,19 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 if (chain)
                     lines.push(`  chain: ${chain}`);
             }
+            // One explanation for the whole list — repeating it per entry buries the
+            // ids it qualifies.
+            if (anyUnqueried) {
+                lines.push(`\n> Tiers marked "Not queried" were skipped because this deployment has not configured them, so those searches are incomplete — a deployment with those tiers configured may still resolve the affected ids.`);
+            }
+        }
+        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`, `Re-call \`pubmed_fetch_fulltext\` with these ${d.idType} ids as \`${d.idType}s\`: ${d.ids.join(', ')}`);
         }
-        if (result.totalReturned === 0) {
+        // An empty response under a budget is a deferral, not an absence — the
+        // articles resolved and the ids above retrieve them.
+        if (result.totalReturned === 0 && !result.deferred) {
             lines.push(`\n> No full-text articles returned. Articles must be open-access and indexed in PMC, Europe PMC, or recoverable via Unpaywall to retrieve full text. For metadata and abstracts only, use \`pubmed_fetch_articles\`.`);
         }
         if (result.truncation)
@@ -1272,6 +1518,7 @@ async function runEpmcStage(epmc, args) {
         Promise.all(args.doiCandidates.map(fetchForDoi)),
     ]);
     const articles = [];
+    const articleInputIds = new Map();
     const remainingPmid = [];
     const remainingPmcid = [];
     const remainingDoi = [];
@@ -1281,8 +1528,9 @@ async function runEpmcStage(epmc, args) {
     const sectionFilterMisses = [];
     const truncatedArticles = [];
     let omittedSections = 0;
-    const collectHit = (run) => {
+    const collectHit = (candidateId, run) => {
         articles.push(run.article);
+        articleInputIds.set(run.article, candidateId);
         if (run.sectionFilterMiss)
             sectionFilterMisses.push(articleDisplayId(run.article));
         if (run.truncation)
@@ -1292,26 +1540,27 @@ async function runEpmcStage(epmc, args) {
     for (const run of pmidResults) {
         pmidOutcomes.set(run.c.pmid, run.outcome);
         if (run.article)
-            collectHit({ ...run, article: run.article });
+            collectHit(run.c.pmid, { ...run, article: run.article });
         else
             remainingPmid.push(run.c);
     }
     for (const run of pmcidResults) {
         pmcidOutcomes.set(run.c.normalized, run.outcome);
         if (run.article)
-            collectHit({ ...run, article: run.article });
+            collectHit(run.c.normalized, { ...run, article: run.article });
         else
             remainingPmcid.push(run.doi && !run.c.c.doi ? { ...run.c.c, doi: run.doi } : run.c.c);
     }
     for (const run of doiResults) {
         doiOutcomes.set(run.c.doi, run.outcome);
         if (run.article)
-            collectHit({ ...run, article: run.article });
+            collectHit(run.c.doi, { ...run, article: run.article });
         else
             remainingDoi.push(run.c);
     }
     return {
         articles,
+        articleInputIds,
         remainingPmid,
         remainingPmcid,
         remainingDoi,
@@ -1614,11 +1863,15 @@ function unpaywallReasonToTierOutcome(reason) {
     }
 }
 /**
- * Derive the terminal `reason` shown on the unavailable entry from its chain.
- * Skips `not-attempted` entries when summarizing — those record config state,
- * not content state, so they make a misleading `reason` when an earlier tier
- * produced a real signal (`pmc:miss`, `unpaywall:no-oa`, etc.). Only when every
- * tier was skipped does `reason` fall back to `no-pmc-fallback-disabled`.
+ * Derive the `reason` shown on the unavailable entry from its chain: the most
+ * specific content signal the last tier that actually answered reported.
+ *
+ * Skipped tiers are deliberately not folded in here. A configuration note in
+ * place of the content signal would erase the one specific thing the chain
+ * learned; the incompleteness is reported alongside it, on `unqueriedTiers`,
+ * where it adds to the answer instead of replacing it. A chain where no tier
+ * was attempted at all has no signal to report and stays
+ * `no-pmc-fallback-disabled`.
  */
 function reasonFromChain(chain) {
     let lastSignal;
@@ -1628,6 +1881,13 @@ function reasonFromChain(chain) {
     }
     if (!lastSignal)
         return 'no-pmc-fallback-disabled';
+    // Unpaywall answering `no-doi` for an id the content tiers never found adds
+    // nothing: record absence is the specific signal, so it stays `not-found`.
+    if (lastSignal.tier === 'unpaywall' && lastSignal.outcome === 'no-doi') {
+        const lastContentSignal = chain.findLast((t) => t.tier !== 'unpaywall' && t.outcome !== 'not-attempted');
+        if (lastContentSignal?.outcome === 'miss')
+            return 'not-found';
+    }
     const key = `${lastSignal.tier}:${lastSignal.outcome}`;
     switch (key) {
         case 'pmc:miss':
@@ -1655,6 +1915,26 @@ function reasonFromChain(chain) {
     }
 }
 // ─── format() helpers ────────────────────────────────────────────────────────
+/** Human-readable tier names for the unqueried-tier line. */
+const UNQUERIED_TIER_LABELS = {
+    europepmc: 'Europe PMC',
+    unpaywall: 'Unpaywall',
+};
+/**
+ * Name each unqueried tier with the reason its chain entry gave for skipping it,
+ * so a `content[]` reader learns which setting is missing without decoding the
+ * chain line. The detail goes through the same sanitizer the chain does — it is
+ * the same upstream string. (#110)
+ */
+function formatUnqueriedTiers(tiers, chain) {
+    return tiers
+        .map((tier) => {
+        const detail = chain.find((t) => t.tier === tier && t.outcome === 'not-attempted')?.detail;
+        const label = UNQUERIED_TIER_LABELS[tier];
+        return detail ? `${label} (${sanitizeChainDetail(detail)})` : label;
+    })
+        .join(', ');
+}
 /**
  * Render the response-level character accounting. Every field is rendered
  * unconditionally so `content[]` readers see the same budget detail
@@ -1739,20 +2019,8 @@ function formatPmcArticle(a, lines, truncation) {
         lines.push(truncationNote(truncation));
     if (a.abstract)
         lines.push(`\n#### Abstract\n${a.abstract}`);
-    for (const sec of a.sections) {
-        if (sec.title)
-            lines.push(`\n#### ${formatHeading(sec.label, sec.title)}`);
-        if (sec.text)
-            lines.push(sec.text);
-        if (sec.subsections?.length) {
-            for (const sub of sec.subsections) {
-                if (sub.title)
-                    lines.push(`\n##### ${formatHeading(sub.label, sub.title)}`);
-                if (sub.text)
-                    lines.push(sub.text);
-            }
-        }
-    }
+    for (const sec of a.sections)
+        formatSection(sec, lines, 4);
     if (a.references?.length) {
         lines.push(`\n#### References (${a.references.length})`);
         for (const ref of a.references) {
@@ -1804,6 +2072,21 @@ function formatPmcAuthor(au) {
 function formatHeading(label, title) {
     return label ? `${label} ${title}` : title;
 }
+/**
+ * Render one body 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)
+ */
+function formatSection(section, lines, depth) {
+    if (section.title) {
+        lines.push(`\n${'#'.repeat(Math.min(depth, 6))} ${formatHeading(section.label, section.title)}`);
+    }
+    if (section.text)
+        lines.push(section.text);
+    for (const sub of section.subsections ?? [])
+        formatSection(sub, lines, depth + 1);
+}
 /**
  * Strip absolute URLs from chain detail strings. Upstream errors (e.g.
  * `Fetch failed for <eutils URL>. Status: 400`) leak endpoint paths and query