@cyanheads/pubmed-mcp-server 2.9.9 → 2.10.0

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

@@ -30,6 +30,7 @@ import { ensureArray } from '../../../services/ncbi/parsing/xml-helpers.js';
 import { getUnpaywallService, } from '../../../services/unpaywall/unpaywall-service.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, SCHEMA_SCHOLARLY_ARTICLE } from './_concepts.js';
 import { pmidStringSchema } from './_schemas.js';
+import { sliceCodeUnits } from './_text.js';
 function normalizePmcId(id) {
     return id.replace(/^PMC/i, '');
 }
@@ -64,10 +65,22 @@ function applyPmcFilters(article, filters) {
 function isSectionFilterMiss(before, after, sectionFilter) {
     return (Boolean(sectionFilter?.length) && before.sections.length > 0 && after.sections.length === 0);
 }
-/** Pick the best human-readable identifier for an article whose section filter
- *  missed, for the recovery notice. Treats empty strings as absent — EPMC-only
+/**
+ * True when the upstream JATS carried no body sections at all — front matter and
+ * abstract only. Publishers that block full-text XML download still return an
+ * `<article>` with a populated `<front>`, so the parsed article looks like a hit
+ * 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)
+ */
+function isBodylessArticle(before) {
+    return before.sections.length === 0;
+}
+/** Pick the best human-readable identifier for an article, for recovery notices
+ *  and character-budget accounting. Treats empty strings as absent — EPMC-only
  *  records carry an empty `pmcId`. */
-function articleSectionMissId(a) {
+function articleDisplayId(a) {
     return [a.pmcId, a.pmid, a.doi, a.epmcId].find((v) => v && v.length > 0) ?? 'article';
 }
 /**
@@ -80,6 +93,21 @@ function buildSectionFilterMissNotice(affectedIds, sectionFilter) {
     const subject = affectedIds.length === 1 ? `article ${affectedIds[0]}` : `articles ${affectedIds.join(', ')}`;
     return `No body sections 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.`;
 }
+/**
+ * Compose the recovery notice for identifiers whose only retrievable record was
+ * metadata-only — PMC or Europe PMC returned front matter with no body, and no
+ * later tier recovered a full-text copy. Points at the tool that still serves
+ * the abstract so the metadata isn't simply lost.
+ *
+ * States what the chain observed rather than asserting the article has no body:
+ * a later tier may well have located an open-access copy and failed to download
+ * it (`unpaywall:fetch-failed`), so the per-tier outcomes are the honest answer
+ * and the notice defers to them. (#86)
+ */
+function buildBodylessNotice(affectedIds) {
+    const subject = affectedIds.length === 1 ? `article ${affectedIds[0]}` : `articles ${affectedIds.join(', ')}`;
+    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 ─────────────────────────────────────────────────────────────────
 const SubsectionSchema = z
     .object({
@@ -173,10 +201,14 @@ const UnpaywallArticleSchema = z
     contentFormat: z
         .enum(['html-markdown', 'pdf-text'])
         .describe('How `content` was extracted. html-markdown: Defuddle extracted Markdown from an HTML landing page; light section structure may survive but is not guaranteed. pdf-text: unpdf extracted plain text from a PDF; no section, reference, or heading structure.'),
+    pmcId: z
+        .string()
+        .optional()
+        .describe('PMC ID this article was requested under, in `PMC<digits>` form — present for `pmcids` input, absent for `pmids` and `dois` input. Ties the article back to the requested identifier, which `unavailable[]` keys on for the ids that found nothing.'),
     pmid: z
         .string()
         .optional()
-        .describe('PubMed ID when input was `pmids`; absent for `dois` input'),
+        .describe('PubMed ID when input was `pmids`; absent for `pmcids` and `dois` input'),
     pubmedUrl: z.string().optional().describe('PubMed URL — present when `pmid` is set'),
     doi: z.string().describe('DOI used to locate the open-access copy'),
     sourceUrl: z.string().describe('URL the content was fetched from'),
@@ -209,25 +241,27 @@ const UnavailableReasonSchema = z
     'not-found',
     'no-pmc-fallback-disabled',
     'no-epmc-fulltext',
+    'no-body',
     'no-doi',
     'no-oa',
     'fetch-failed',
     '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-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. 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).');
 const TierOutcomeSchema = z
     .enum([
     'not-attempted',
     'miss',
     'no-fulltext',
+    'no-body',
     'no-doi',
     'no-oa',
     'fetch-failed',
     'parse-failed',
     'service-error',
 ])
-    .describe('Per-tier outcome. not-attempted: tier was skipped. miss: tier returned no record. no-fulltext: EPMC indexed the record but publishes no fullTextXML. no-doi: no DOI to query Unpaywall. no-oa: Unpaywall reports no open-access copy. fetch-failed: OA copy download failed. parse-failed: extraction produced empty content. service-error: tier service threw.');
+    .describe('Per-tier outcome. not-attempted: tier was skipped. miss: tier returned no record. no-fulltext: EPMC indexed the record but publishes no fullTextXML. no-body: the tier returned a record with front matter and abstract but no body sections, so the chain continued. no-doi: no DOI to query Unpaywall. no-oa: Unpaywall reports no open-access copy. fetch-failed: OA copy download failed. parse-failed: extraction produced empty content. service-error: tier service threw.');
 const TriedTierSchema = z
     .object({
     tier: z.enum(['pmc', 'europepmc', 'unpaywall']).describe('Which tier in the resolution chain'),
@@ -247,6 +281,234 @@ const UnavailableSchema = z
         .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.'),
 })
     .describe('One identifier that could not be returned, with the full chain it traversed');
+// ─── Character-budget schemas ────────────────────────────────────────────────
+const TruncatedSectionSchema = z
+    .object({
+    title: z.string().optional().describe('Section heading, when the section carries one'),
+    originalCharacters: z
+        .number()
+        .describe('Body characters this section carried before the budget pass'),
+    returnedCharacters: z
+        .number()
+        .describe('Body characters this section carries in the response. Zero means the section was dropped in `truncate` mode, or kept as a heading-only entry in `outline` mode.'),
+    truncated: z
+        .boolean()
+        .describe('True when the section returned fewer characters than it originally carried'),
+})
+    .describe('Character accounting for one body section of a budgeted article');
+const TruncatedArticleSchema = z
+    .object({
+    id: z
+        .string()
+        .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'),
+    originalCharacters: z
+        .number()
+        .describe('Body characters this article carried before the budget pass'),
+    returnedCharacters: z.number().describe('Body characters this article carries in the response'),
+    sections: z
+        .array(TruncatedSectionSchema)
+        .optional()
+        .describe('Per-section accounting for `source: pmc` articles, in document order, including sections dropped for budget. Absent for `source: unpaywall`, whose body has no section structure.'),
+})
+    .describe('Character accounting for one article the budget shortened');
+const TruncationSchema = z
+    .object({
+    mode: z
+        .enum(['truncate', 'outline'])
+        .describe('The `overflowMode` that produced these results'),
+    maxCharacters: z.number().optional().describe('The `maxCharacters` budget applied, when set'),
+    maxCharactersPerSection: z
+        .number()
+        .optional()
+        .describe('The `maxCharactersPerSection` budget applied, when set'),
+    originalCharacters: z
+        .number()
+        .describe('Body characters the shortened articles carried before the budget pass'),
+    returnedCharacters: z
+        .number()
+        .describe('Body characters the shortened articles carry in this response'),
+    omittedSections: z
+        .number()
+        .describe('Body sections dropped entirely because an article budget was exhausted before reaching them. Always 0 in `outline` mode, which keeps every heading.'),
+    articles: z
+        .array(TruncatedArticleSchema)
+        .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.');
+/** 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'. */
+function sectionCharacters(section) {
+    return (section.text.length + (section.subsections?.reduce((n, sub) => n + sub.text.length, 0) ?? 0));
+}
+/**
+ * Shorten an ordered list of text fields so their combined length fits
+ * `allowance`. Fields are filled in order, so earlier fields survive whole and
+ * later ones absorb the shortfall — the section's own text before its
+ * subsections. Cuts at the character boundary with no appended marker so the
+ * reported `returnedCharacters` is exact; `format()` carries the human-visible
+ * note. A cut that would split a surrogate pair backs off a code unit, so a
+ * field can return one character under its share — counts are measured off the
+ * returned text, never off the allowance. (#93)
+ */
+function fitFields(fields, allowance) {
+    let remaining = Math.max(allowance, 0);
+    return fields.map((text) => {
+        const kept = sliceCodeUnits(text, remaining);
+        remaining -= kept.length;
+        return kept;
+    });
+}
+/**
+ * Split `total` evenly across sections, then hand the leftover from sections
+ * that need less than their share back to the ones still capped, until the
+ * budget is spent or every section holds all it can. Equal shares alone would
+ * strand budget on short sections — a ten-section article with two one-line
+ * sections would return well under what the caller asked for.
+ */
+function evenShares(caps, total) {
+    const allowances = caps.map(() => 0);
+    let remaining = total;
+    while (remaining > 0) {
+        const hungry = caps.reduce((acc, cap, i) => {
+            if ((allowances[i] ?? 0) < cap)
+                acc.push(i);
+            return acc;
+        }, []);
+        if (hungry.length === 0)
+            break;
+        const share = Math.floor(remaining / hungry.length);
+        // Fewer characters left than sections still wanting them: hand out the
+        // remainder one character at a time so the budget is fully spent.
+        for (const i of hungry) {
+            const want = (caps[i] ?? 0) - (allowances[i] ?? 0);
+            const give = Math.min(share === 0 ? 1 : share, want, remaining);
+            allowances[i] = (allowances[i] ?? 0) + give;
+            remaining -= give;
+            if (remaining === 0)
+                break;
+        }
+    }
+    return allowances;
+}
+/**
+ * Decide how many characters each top-level section may keep.
+ *
+ * `truncate` fills sections greedily in document order: early sections keep
+ * their full text and sections reached after the budget is spent get nothing.
+ * `outline` spreads `maxCharacters` across every section instead, so each
+ * heading survives with an excerpt rather than the budget being consumed by the
+ * first sections. `maxCharactersPerSection` caps each section under either mode.
+ */
+function allotSectionBudgets(sizes, budget) {
+    const perSection = budget.maxCharactersPerSection;
+    const total = budget.maxCharacters;
+    if (budget.overflowMode === 'outline' && total !== undefined) {
+        return evenShares(sizes.map((size) => Math.min(perSection ?? size, size)), total);
+    }
+    let remaining = total ?? sizes.reduce((sum, size) => sum + size, 0);
+    return sizes.map((size) => {
+        const allowance = Math.min(perSection ?? size, size, remaining);
+        remaining -= allowance;
+        return allowance;
+    });
+}
+/**
+ * Apply the character budget to a JATS article's body. Runs as a pure
+ * post-processing pass after `applyPmcFilters`, so `sections` / `maxSections` /
+ * `includeReferences` and the empty-body signals they feed are unaffected.
+ * Titles, abstracts, identifiers, and references are never counted or cut —
+ * the budget only spends on body text, keeping every article citable.
+ *
+ * Returns the article untouched (same object identity) when no budget was
+ * requested or nothing exceeded it. A section left with zero characters is
+ * dropped in `truncate` mode and counted as omitted; `outline` keeps it as a
+ * heading-only entry. Dropped sections still appear in the accounting so the
+ * caller can see which headings exist. (#81)
+ */
+function applyPmcBudget(article, budget) {
+    if (!budgetRequested(budget) || article.sections.length === 0) {
+        return { article, omittedSections: 0 };
+    }
+    const sizes = article.sections.map(sectionCharacters);
+    const originalCharacters = sizes.reduce((sum, size) => sum + size, 0);
+    const allowances = allotSectionBudgets(sizes, budget);
+    const kept = [];
+    const sectionReports = [];
+    let omittedSections = 0;
+    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 returned = fitted.reduce((sum, text) => sum + text.length, 0);
+        returnedCharacters += returned;
+        sectionReports.push({
+            ...(section.title !== undefined && { title: section.title }),
+            originalCharacters: original,
+            returnedCharacters: returned,
+            truncated: returned < original,
+        });
+        if (returned === 0 && original > 0 && budget.overflowMode === 'truncate') {
+            omittedSections += 1;
+            return;
+        }
+        kept.push({
+            ...section,
+            text: fitted[0] ?? '',
+            ...(section.subsections && {
+                subsections: section.subsections.map((sub, j) => ({ ...sub, text: fitted[j + 1] ?? '' })),
+            }),
+        });
+    });
+    if (returnedCharacters === originalCharacters && omittedSections === 0) {
+        return { article, omittedSections: 0 };
+    }
+    return {
+        article: { ...article, sections: kept },
+        omittedSections,
+        truncation: { originalCharacters, returnedCharacters, sections: sectionReports },
+    };
+}
+/**
+ * Apply the character budget to an Unpaywall body. That body is one
+ * unstructured blob — HTML-as-Markdown or PDF-as-text — so only `maxCharacters`
+ * applies, and `outline` mode has no headings to preserve and behaves like
+ * `truncate`. (#81)
+ */
+function applyContentBudget(content, budget) {
+    const cap = budget.maxCharacters;
+    if (cap === undefined || content.length <= cap)
+        return { content };
+    const kept = sliceCodeUnits(content, cap);
+    return {
+        content: kept,
+        truncation: { originalCharacters: content.length, returnedCharacters: kept.length },
+    };
+}
+/**
+ * Compose the recovery notice for a budgeted response. Names what was spent and
+ * where the detail lives so an agent reading only `content[]` knows the body it
+ * received is partial. (#81)
+ */
+function buildTruncationNotice(truncation) {
+    const subject = truncation.articles.length === 1 ? '1 article' : `${truncation.articles.length} articles`;
+    const omitted = truncation.omittedSections > 0
+        ? ` ${truncation.omittedSections} section(s) were dropped once the budget ran out.`
+        : '';
+    // Name only the budgets the request actually set — pointing at `maxCharacters`
+    // when the caller only capped per-section sends them to a knob that is unset.
+    const knobs = [
+        truncation.maxCharacters !== undefined ? '`maxCharacters`' : undefined,
+        truncation.maxCharactersPerSection !== undefined ? '`maxCharactersPerSection`' : undefined,
+    ].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.`;
+}
 // ─── Tool Definition ─────────────────────────────────────────────────────────
 /**
  * Compose the tool description for the fallback tiers enabled in this
@@ -306,7 +568,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             .min(1)
             .max(10)
             .optional()
-            .describe('PMC IDs to fetch (e.g. ["PMC9575052"]). Provide exactly one of `pmcids`, `pmids`, or `dois`.'),
+            .describe('PMC IDs to fetch (e.g. ["PMC9575052"]). Provide exactly one of `pmcids`, `pmids`, or `dois`. 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)
@@ -334,6 +596,24 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             .array(z.string())
             .optional()
             .describe('Filter to specific sections by title, case-insensitive (e.g. ["Introduction", "Methods", "Results", "Discussion"]). 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, 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.'),
+        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.'),
+        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 and sections past the budget are dropped (counted in `truncation.omittedSections`). outline: split the budget evenly so every section keeps its heading, and an excerpt as far as the budget reaches — 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.'),
     })
         .refine((v) => [v.pmcids, v.pmids, v.dois].filter((b) => b !== undefined).length === 1, {
         message: 'Provide exactly one of `pmcids`, `pmids`, or `dois` (not zero, not more).',
@@ -345,15 +625,18 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             .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.'),
+        truncation: TruncationSchema.optional(),
     }),
-    // Recovery guidance when a `sections` filter removes every body section from
-    // an article that has one — agent-facing context surfaced via ctx.enrich.notice()
-    // to structuredContent and content[]; absent when no filter ran or sections matched. (#80)
+    // Recovery guidance for three 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.
     enrichment: {
         notice: z
             .string()
             .optional()
-            .describe('Optional guidance when a `sections` filter removed every body section — names the requested section terms and the affected article id(s), and suggests retrying without `sections` or using broader headings. Absent when no section filter was applied or sections matched.'),
+            .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.'),
     },
     async handler(input, ctx) {
         ctx.log.info('Executing pubmed_fetch_fulltext', {
@@ -380,6 +663,22 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // 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
+        // unrecovered at the end drive the metadata-only recovery notice (#86).
+        const bodylessInputIds = new Set();
+        // Per-article character accounting collected across all three stages, plus
+        // the running count of sections the budget dropped. Empty when no budget was
+        // requested or nothing exceeded it (#81).
+        const truncatedArticles = [];
+        let omittedSections = 0;
+        const budget = {
+            overflowMode: input.overflowMode,
+            ...(input.maxCharacters !== undefined && { maxCharacters: input.maxCharacters }),
+            ...(input.maxCharactersPerSection !== undefined && {
+                maxCharactersPerSection: input.maxCharactersPerSection,
+            }),
+        };
         const idType = input.pmids ? 'pmid' : input.pmcids ? 'pmcid' : 'doi';
         // ── Branch routing → produce buckets the staged chain consumes ──────────
         let pmcIds = [];
@@ -511,19 +810,35 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 if (!articleSet) {
                     throw new Error('PMC EFetch response missing pmc-articleset wrapper');
                 }
-                const parsed = findAll(articleSet, 'article').map((node) => {
+                // A parsed article with no body sections is front matter only — PMC
+                // returns one whenever the publisher blocks full-text XML download. It
+                // is not a hit: it never enters `articles[]`, and its id is routed to
+                // the remaining tiers like any other PMC miss. (#86)
+                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);
+                        continue;
+                    }
                     const after = applyPmcFilters(before, input);
                     if (isSectionFilterMiss(before, after, input.sections)) {
-                        sectionFilterMisses.push(articleSectionMissId(after));
+                        sectionFilterMisses.push(articleDisplayId(after));
                     }
-                    return after;
-                });
-                pmcArticles = parsed.map((a) => ({
-                    source: 'pmc',
-                    viaSource: 'pmc',
-                    ...a,
-                }));
+                    const budgeted = applyPmcBudget(after, budget);
+                    omittedSections += budgeted.omittedSections;
+                    if (budgeted.truncation) {
+                        truncatedArticles.push({
+                            id: articleDisplayId(after),
+                            source: 'pmc',
+                            ...budgeted.truncation,
+                        });
+                    }
+                    parsed.push({ source: 'pmc', viaSource: 'pmc', ...budgeted.article });
+                }
+                pmcArticles = parsed;
                 const returnedPmcIds = new Set(pmcArticles.map((a) => a.pmcId).filter((id) => !!id));
                 for (const prefixed of returnedPmcIds) {
                     recoveredIds.add(pmcidToInputId.get(prefixed) ?? prefixed);
@@ -533,7 +848,17 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                     .filter((id) => !returnedPmcIds.has(id));
                 for (const prefixed of missing) {
                     const inputId = pmcidToInputId.get(prefixed) ?? prefixed;
-                    chainByInput.get(inputId)?.push({ tier: 'pmc', outcome: 'miss' });
+                    if (bodylessPmcIds.has(prefixed)) {
+                        bodylessInputIds.add(inputId);
+                        chainByInput.get(inputId)?.push({
+                            tier: 'pmc',
+                            outcome: 'no-body',
+                            detail: 'PMC returned front matter and abstract only, with no body sections',
+                        });
+                    }
+                    else {
+                        chainByInput.get(inputId)?.push({ tier: 'pmc', outcome: 'miss' });
+                    }
                 }
                 routePmcMissesToFallback(missing);
             }
@@ -559,6 +884,7 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 pmcidFallbackCandidates,
                 doiCandidates,
                 input,
+                budget,
                 ctx,
             })
             : {
@@ -570,8 +896,12 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 pmcidOutcomes: new Map(),
                 doiOutcomes: new Map(),
                 sectionFilterMisses: [],
+                truncatedArticles: [],
+                omittedSections: 0,
             };
         pmcArticles = pmcArticles.concat(epmcOutcomes.articles);
+        truncatedArticles.push(...epmcOutcomes.truncatedArticles);
+        omittedSections += epmcOutcomes.omittedSections;
         // Fold EPMC outcomes into each id's chain. EPMC-served articles count as
         // recovered, so their ids are added to `recoveredIds` here.
         if (!epmc) {
@@ -590,28 +920,22 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 chainByInput.get(c.doi)?.push(epmcDisabledEntry);
         }
         else {
-            for (const [pmid, outcome] of epmcOutcomes.pmidOutcomes) {
-                if (outcome.kind === 'hit') {
-                    recoveredIds.add(pmid);
-                    continue;
-                }
-                chainByInput.get(pmid)?.push(epmcTierFromOutcome(outcome));
-            }
-            for (const [prefixed, outcome] of epmcOutcomes.pmcidOutcomes) {
-                const inputId = pmcidToInputId.get(prefixed) ?? prefixed;
+            const foldEpmcOutcome = (inputId, outcome) => {
                 if (outcome.kind === 'hit') {
                     recoveredIds.add(inputId);
-                    continue;
+                    return;
                 }
+                if (outcome.kind === 'no-body')
+                    bodylessInputIds.add(inputId);
                 chainByInput.get(inputId)?.push(epmcTierFromOutcome(outcome));
+            };
+            for (const [pmid, outcome] of epmcOutcomes.pmidOutcomes)
+                foldEpmcOutcome(pmid, outcome);
+            for (const [prefixed, outcome] of epmcOutcomes.pmcidOutcomes) {
+                foldEpmcOutcome(pmcidToInputId.get(prefixed) ?? prefixed, outcome);
             }
-            for (const [doi, outcome] of epmcOutcomes.doiOutcomes) {
-                if (outcome.kind === 'hit') {
-                    recoveredIds.add(doi);
-                    continue;
-                }
-                chainByInput.get(doi)?.push(epmcTierFromOutcome(outcome));
-            }
+            for (const [doi, outcome] of epmcOutcomes.doiOutcomes)
+                foldEpmcOutcome(doi, outcome);
         }
         pmidFallbackCandidates = epmcOutcomes.remainingPmid;
         pmcidFallbackCandidates = epmcOutcomes.remainingPmcid;
@@ -620,15 +944,78 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // ── Stage 3: Unpaywall fallback ─────────────────────────────────────────
         const unpaywall = getUnpaywallService();
         const fallbackArticles = [];
-        // PMC misses on `pmcids` input don't get an Unpaywall attempt — the current
-        // implementation doesn't resolve PMCID → DOI for that branch.
-        for (const c of pmcidFallbackCandidates) {
-            const prefixed = withPmcPrefix(c.pmcid);
-            chainByInput.get(pmcidToInputId.get(prefixed) ?? prefixed)?.push({
-                tier: 'unpaywall',
-                outcome: 'not-attempted',
-                detail: 'pmcids input does not resolve a DOI for Unpaywall',
-            });
+        // `pmcids` input reaches Unpaywall on the DOI the chain already holds: the
+        // EPMC stage searches by PMCID and its hit carries one, captured on non-hit
+        // outcomes too. PMCIDs EPMC never resolved fall back to the PMC ID
+        // Converter, which returns DOIs for PMC-indexed records. (#88)
+        if (pmcidFallbackCandidates.length > 0) {
+            if (!unpaywall) {
+                for (const c of pmcidFallbackCandidates) {
+                    const prefixed = withPmcPrefix(c.pmcid);
+                    chainByInput.get(pmcidToInputId.get(prefixed) ?? prefixed)?.push({
+                        tier: 'unpaywall',
+                        outcome: 'not-attempted',
+                        detail: 'UNPAYWALL_EMAIL is not set',
+                    });
+                }
+            }
+            else {
+                const needDoi = pmcidFallbackCandidates
+                    .filter((c) => !c.doi)
+                    .map((c) => withPmcPrefix(c.pmcid));
+                if (needDoi.length > 0) {
+                    try {
+                        const records = await getNcbiService().idConvert(needDoi, 'pmcid', ctx.signal ? { signal: ctx.signal } : undefined);
+                        const doiByPmcid = new Map();
+                        for (const r of records) {
+                            if (r.pmcid && r.doi) {
+                                doiByPmcid.set(withPmcPrefix(normalizePmcId(String(r.pmcid))), String(r.doi));
+                            }
+                        }
+                        pmcidFallbackCandidates = pmcidFallbackCandidates.map((c) => {
+                            if (c.doi)
+                                return c;
+                            const doi = doiByPmcid.get(withPmcPrefix(c.pmcid));
+                            return doi ? { ...c, doi } : c;
+                        });
+                    }
+                    catch (error) {
+                        ctx.log.warning('Failed to resolve PMCID → DOI for the Unpaywall fallback', {
+                            error: error instanceof Error ? error.message : String(error),
+                            pmcidCount: needDoi.length,
+                        });
+                    }
+                }
+                const outcomes = await Promise.all(pmcidFallbackCandidates.map(async (candidate) => {
+                    // The prefixed PMCID is the id `unavailable[]` keys on, so stamping
+                    // it on the article makes a partially-recovered batch report its
+                    // successes and its failures under the same identifier. (#92)
+                    const pmcId = withPmcPrefix(candidate.pmcid);
+                    return {
+                        pmcId,
+                        result: candidate.doi
+                            ? await resolveUnpaywall({ pmcId, doi: candidate.doi, budget }, unpaywall, ctx)
+                            : { unavailable: { reason: 'no-doi' } },
+                    };
+                }));
+                for (const { pmcId, result } of outcomes) {
+                    const inputId = pmcidToInputId.get(pmcId) ?? pmcId;
+                    if ('article' in result) {
+                        fallbackArticles.push(result.article);
+                        if (result.truncation)
+                            truncatedArticles.push(result.truncation);
+                        recoveredIds.add(inputId);
+                    }
+                    else {
+                        const u = result.unavailable;
+                        chainByInput.get(inputId)?.push({
+                            tier: 'unpaywall',
+                            outcome: unpaywallReasonToTierOutcome(u.reason),
+                            ...(u.detail && { detail: u.detail }),
+                        });
+                    }
+                }
+            }
         }
         if (pmidFallbackCandidates.length > 0) {
             // The PMC ID Converter only returns DOIs for articles it has in PMC, so
@@ -665,12 +1052,14 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 const outcomes = await Promise.all(pmidFallbackCandidates.map(async (candidate) => ({
                     candidate,
                     result: candidate.doi
-                        ? await resolveUnpaywall({ pmid: candidate.pmid, doi: candidate.doi }, unpaywall, ctx)
+                        ? await resolveUnpaywall({ pmid: candidate.pmid, doi: candidate.doi, budget }, unpaywall, ctx)
                         : { unavailable: { reason: 'no-doi' } },
                 })));
                 for (const { candidate, result } of outcomes) {
                     if ('article' in result) {
                         fallbackArticles.push(result.article);
+                        if (result.truncation)
+                            truncatedArticles.push(result.truncation);
                         recoveredIds.add(candidate.pmid);
                     }
                     else {
@@ -699,11 +1088,13 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 // doesn't reject under normal operation.
                 const outcomes = await Promise.all(doiCandidates.map(async (c) => ({
                     doi: c.doi,
-                    result: await resolveUnpaywall({ doi: c.doi }, unpaywall, ctx),
+                    result: await resolveUnpaywall({ doi: c.doi, budget }, unpaywall, ctx),
                 })));
                 for (const { doi, result } of outcomes) {
                     if ('article' in result) {
                         fallbackArticles.push(result.article);
+                        if (result.truncation)
+                            truncatedArticles.push(result.truncation);
                         recoveredIds.add(doi);
                     }
                     else {
@@ -738,13 +1129,40 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             unpaywallHits: fallbackArticles.length,
             unavailable: unavailable.length,
         });
+        // Rolled up only when the budget actually removed characters, so an
+        // under-budget request returns exactly what it did before the budget
+        // controls existed. (#81)
+        const truncation = truncatedArticles.length > 0
+            ? {
+                mode: input.overflowMode,
+                ...(input.maxCharacters !== undefined && { maxCharacters: input.maxCharacters }),
+                ...(input.maxCharactersPerSection !== undefined && {
+                    maxCharactersPerSection: input.maxCharactersPerSection,
+                }),
+                originalCharacters: truncatedArticles.reduce((n, a) => n + a.originalCharacters, 0),
+                returnedCharacters: truncatedArticles.reduce((n, a) => n + a.returnedCharacters, 0),
+                omittedSections,
+                articles: truncatedArticles,
+            }
+            : undefined;
+        // Only the last ctx.enrich.notice survives, so the applicable fragments are
+        // collected and emitted once.
+        const notices = [];
         if (input.sections?.length && sectionFilterMisses.length > 0) {
-            ctx.enrich.notice(buildSectionFilterMissNotice(sectionFilterMisses, input.sections));
+            notices.push(buildSectionFilterMissNotice(sectionFilterMisses, input.sections));
         }
+        const unrecoveredBodyless = [...bodylessInputIds].filter((id) => !recoveredIds.has(id));
+        if (unrecoveredBodyless.length > 0)
+            notices.push(buildBodylessNotice(unrecoveredBodyless));
+        if (truncation)
+            notices.push(buildTruncationNotice(truncation));
+        if (notices.length > 0)
+            ctx.enrich.notice(notices.join(' '));
         return {
             articles,
             totalReturned: articles.length,
             ...(unavailable.length > 0 && { unavailable }),
+            ...(truncation && { truncation }),
         };
     },
     format: (result) => {
@@ -766,12 +1184,16 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         if (result.totalReturned === 0) {
             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)
+            formatTruncation(result.truncation, lines);
+        const truncationById = new Map(result.truncation?.articles.map((t) => [t.id, t]) ?? []);
         for (const a of result.articles) {
             lines.push('');
+            const t = truncationById.get(articleDisplayId(a));
             if (a.source === 'pmc')
-                formatPmcArticle(a, lines);
+                formatPmcArticle(a, lines, t);
             else
-                formatUnpaywallArticle(a, lines);
+                formatUnpaywallArticle(a, lines, t);
         }
         return [{ type: 'text', text: lines.join('\n') }];
     },
@@ -795,27 +1217,44 @@ async function runEpmcStage(epmc, args) {
         }
         if (search.kind === 'miss')
             return { c, outcome: { kind: 'miss' } };
+        const doi = search.hit.doi ? { doi: search.hit.doi } : {};
         const fetched = await fetchEpmcArticle(epmc, search.hit, args, contextPmid);
         if (fetched.kind === 'error') {
-            return { c, outcome: { kind: 'service-error', detail: fetched.detail } };
+            return { c, ...doi, outcome: { kind: 'service-error', detail: fetched.detail } };
         }
         if (fetched.kind === 'no-fulltext') {
             return {
                 c,
+                ...doi,
                 outcome: { kind: 'no-fulltext', ...(fetched.detail && { detail: fetched.detail }) },
             };
         }
+        if (fetched.kind === 'no-body') {
+            return { c, ...doi, outcome: { kind: 'no-body', detail: fetched.detail } };
+        }
         return {
             c,
+            ...doi,
             outcome: { kind: 'hit' },
             article: fetched.article,
             sectionFilterMiss: fetched.sectionFilterMiss,
+            omittedSections: fetched.omittedSections,
+            ...(fetched.truncation && { truncation: fetched.truncation }),
         };
     };
-    const fetchForPmid = (c) => runOne(c, `EXT_ID:"${c.pmid}" AND SRC:MED`, c.pmid);
+    /**
+     * Query shapes are load-bearing and not interchangeable with their quoted
+     * variants. Europe PMC matches zero records for `EXT_ID:"<pmid>" AND SRC:MED`
+     * and `PMCID:"PMC<digits>"` — the quotes only survive as long as no `AND SRC:`
+     * clause follows. `SRC:PMC` is likewise wrong for a PMCID lookup: EPMC's
+     * canonical record for a PMC-indexed article has `source: MED` and carries the
+     * PMCID as a field, so the filter excludes the very record being sought. DOIs
+     * keep their quotes — they carry slashes and dots that need them. (#85)
+     */
+    const fetchForPmid = (c) => runOne(c, `EXT_ID:${c.pmid} AND SRC:MED`, c.pmid);
     const fetchForPmcid = (c) => {
         const normalized = withPmcPrefix(c.pmcid);
-        return runOne({ c, normalized }, `PMCID:"${normalized}" AND SRC:PMC`, undefined);
+        return runOne({ c, normalized }, `PMCID:${normalized}`, undefined);
     };
     const fetchForDoi = (c) => runOne(c, `DOI:"${c.doi}"`, undefined);
     const [pmidResults, pmcidResults, doiResults] = await Promise.all([
@@ -831,35 +1270,36 @@ async function runEpmcStage(epmc, args) {
     const pmcidOutcomes = new Map();
     const doiOutcomes = new Map();
     const sectionFilterMisses = [];
-    for (const { c, outcome, article, sectionFilterMiss } of pmidResults) {
-        pmidOutcomes.set(c.pmid, outcome);
-        if (article) {
-            articles.push(article);
-            if (sectionFilterMiss)
-                sectionFilterMisses.push(articleSectionMissId(article));
-        }
+    const truncatedArticles = [];
+    let omittedSections = 0;
+    const collectHit = (run) => {
+        articles.push(run.article);
+        if (run.sectionFilterMiss)
+            sectionFilterMisses.push(articleDisplayId(run.article));
+        if (run.truncation)
+            truncatedArticles.push(run.truncation);
+        omittedSections += run.omittedSections ?? 0;
+    };
+    for (const run of pmidResults) {
+        pmidOutcomes.set(run.c.pmid, run.outcome);
+        if (run.article)
+            collectHit({ ...run, article: run.article });
         else
-            remainingPmid.push(c);
+            remainingPmid.push(run.c);
     }
-    for (const { c: pair, outcome, article, sectionFilterMiss } of pmcidResults) {
-        pmcidOutcomes.set(pair.normalized, outcome);
-        if (article) {
-            articles.push(article);
-            if (sectionFilterMiss)
-                sectionFilterMisses.push(articleSectionMissId(article));
-        }
+    for (const run of pmcidResults) {
+        pmcidOutcomes.set(run.c.normalized, run.outcome);
+        if (run.article)
+            collectHit({ ...run, article: run.article });
         else
-            remainingPmcid.push(pair.c);
+            remainingPmcid.push(run.doi && !run.c.c.doi ? { ...run.c.c, doi: run.doi } : run.c.c);
     }
-    for (const { c, outcome, article, sectionFilterMiss } of doiResults) {
-        doiOutcomes.set(c.doi, outcome);
-        if (article) {
-            articles.push(article);
-            if (sectionFilterMiss)
-                sectionFilterMisses.push(articleSectionMissId(article));
-        }
+    for (const run of doiResults) {
+        doiOutcomes.set(run.c.doi, run.outcome);
+        if (run.article)
+            collectHit({ ...run, article: run.article });
         else
-            remainingDoi.push(c);
+            remainingDoi.push(run.c);
     }
     return {
         articles,
@@ -870,6 +1310,8 @@ async function runEpmcStage(epmc, args) {
         pmcidOutcomes,
         doiOutcomes,
         sectionFilterMisses,
+        truncatedArticles,
+        omittedSections,
     };
 }
 /**
@@ -923,30 +1365,46 @@ async function fetchEpmcArticle(epmc, hit, args, contextPmid) {
             return { kind: 'no-fulltext', detail: 'EPMC fullTextXML payload had no <article> element' };
         }
         const beforeFilter = parsePmcArticle(articleNode);
+        if (isBodylessArticle(beforeFilter)) {
+            return {
+                kind: 'no-body',
+                detail: 'EPMC fullTextXML carried front matter and abstract only, with no body sections',
+            };
+        }
         const parsed = applyPmcFilters(beforeFilter, args.input);
         const sectionFilterMiss = isSectionFilterMiss(beforeFilter, parsed, args.input.sections);
+        const budgeted = applyPmcBudget(parsed, args.budget);
         // `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.
-        const { pmcId, pmcUrl, ...rest } = parsed;
+        const { pmcId, pmcUrl, ...rest } = budgeted.article;
         const pmid = rest.pmid ?? hit.pmid ?? contextPmid;
         const doi = rest.doi ?? hit.doi;
+        const article = {
+            source: 'pmc',
+            viaSource: 'europepmc',
+            ...rest,
+            ...(pmcId && { pmcId, pmcUrl }),
+            ...(pmid && {
+                pmid,
+                pubmedUrl: rest.pubmedUrl ?? `https://pubmed.ncbi.nlm.nih.gov/${pmid}/`,
+            }),
+            ...(doi && { doi }),
+            epmcId: hit.id,
+            epmcSource: hit.source,
+        };
         return {
             kind: 'article',
             sectionFilterMiss,
-            article: {
-                source: 'pmc',
-                viaSource: 'europepmc',
-                ...rest,
-                ...(pmcId && { pmcId, pmcUrl }),
-                ...(pmid && {
-                    pmid,
-                    pubmedUrl: rest.pubmedUrl ?? `https://pubmed.ncbi.nlm.nih.gov/${pmid}/`,
-                }),
-                ...(doi && { doi }),
-                epmcId: hit.id,
-                epmcSource: hit.source,
-            },
+            article,
+            omittedSections: budgeted.omittedSections,
+            ...(budgeted.truncation && {
+                truncation: {
+                    id: articleDisplayId(article),
+                    source: 'pmc',
+                    ...budgeted.truncation,
+                },
+            }),
         };
     }
     catch (error) {
@@ -987,12 +1445,28 @@ async function fetchPubmedDois(pmids, signal) {
     return out;
 }
 /**
- * Resolve a DOI to an open-access article via Unpaywall. `pmid`, when set,
- * is stamped onto the resulting article so the pmid-input branch carries its
- * cross-reference through.
+ * Resolve a DOI to an open-access article via Unpaywall. `pmcId` and `pmid`,
+ * when set, are stamped onto the resulting article so the branch that requested
+ * it carries its identifier through — Unpaywall itself only knows the DOI.
  */
 async function resolveUnpaywall(args, service, ctx) {
-    const { pmid, doi } = args;
+    const { pmcId, pmid, doi, budget } = args;
+    const requestedIds = { ...(pmcId && { pmcId }), ...(pmid && { pmid }) };
+    /** Budget the extracted body, then pair the article with its accounting. */
+    const budgeted = (build, content) => {
+        const capped = applyContentBudget(content, budget);
+        const article = build(capped.content);
+        return {
+            article,
+            ...(capped.truncation && {
+                truncation: {
+                    id: articleDisplayId(article),
+                    source: 'unpaywall',
+                    ...capped.truncation,
+                },
+            }),
+        };
+    };
     let resolution;
     try {
         resolution = await service.resolve(doi, ctx.signal);
@@ -1029,18 +1503,16 @@ async function resolveUnpaywall(args, service, ctx) {
                     },
                 };
             }
-            return {
-                article: buildUnpaywallArticle({
-                    ...(pmid && { pmid }),
-                    doi,
-                    sourceUrl: content.fetchedUrl,
-                    location: resolution.location,
-                    contentFormat: 'html-markdown',
-                    content: body,
-                    title: extracted.title,
-                    wordCount: extracted.wordCount,
-                }),
-            };
+            return budgeted((text) => buildUnpaywallArticle({
+                ...requestedIds,
+                doi,
+                sourceUrl: content.fetchedUrl,
+                location: resolution.location,
+                contentFormat: 'html-markdown',
+                content: text,
+                title: extracted.title,
+                wordCount: extracted.wordCount,
+            }), body);
         }
         const extracted = await pdfParser.extractText(content.body, { mergePages: true });
         const text = typeof extracted.text === 'string' ? extracted.text.trim() : '';
@@ -1049,17 +1521,15 @@ async function resolveUnpaywall(args, service, ctx) {
                 unavailable: { reason: 'parse-failed', detail: 'PDF extraction produced empty text' },
             };
         }
-        return {
-            article: buildUnpaywallArticle({
-                ...(pmid && { pmid }),
-                doi,
-                sourceUrl: content.fetchedUrl,
-                location: resolution.location,
-                contentFormat: 'pdf-text',
-                content: text,
-                totalPages: extracted.totalPages,
-            }),
-        };
+        return budgeted((body) => buildUnpaywallArticle({
+            ...requestedIds,
+            doi,
+            sourceUrl: content.fetchedUrl,
+            location: resolution.location,
+            contentFormat: 'pdf-text',
+            content: body,
+            totalPages: extracted.totalPages,
+        }), text);
     }
     catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
@@ -1073,6 +1543,7 @@ function buildUnpaywallArticle(args) {
         source: 'unpaywall',
         viaSource: 'unpaywall',
         contentFormat: args.contentFormat,
+        ...(args.pmcId && { pmcId: args.pmcId }),
         ...(args.pmid && {
             pmid: args.pmid,
             pubmedUrl: `https://pubmed.ncbi.nlm.nih.gov/${args.pmid}/`,
@@ -1103,6 +1574,8 @@ function epmcTierFromOutcome(outcome) {
                 outcome: 'no-fulltext',
                 ...(outcome.detail && { detail: outcome.detail }),
             };
+        case 'no-body':
+            return { tier: 'europepmc', outcome: 'no-body', detail: outcome.detail };
         case 'service-error':
             return { tier: 'europepmc', outcome: 'service-error', detail: outcome.detail };
     }
@@ -1116,6 +1589,7 @@ function epmcTierFromOutcome(outcome) {
  */
 function unpaywallReasonToTierOutcome(reason) {
     switch (reason) {
+        case 'no-body':
         case 'no-doi':
         case 'no-oa':
         case 'fetch-failed':
@@ -1152,6 +1626,9 @@ function reasonFromChain(chain) {
             return 'not-found';
         case 'europepmc:no-fulltext':
             return 'no-epmc-fulltext';
+        case 'pmc:no-body':
+        case 'europepmc:no-body':
+            return 'no-body';
         case 'unpaywall:no-doi':
             return 'no-doi';
         case 'unpaywall:no-oa':
@@ -1169,7 +1646,34 @@ function reasonFromChain(chain) {
     }
 }
 // ─── format() helpers ────────────────────────────────────────────────────────
-function formatPmcArticle(a, lines) {
+/**
+ * Render the response-level character accounting. Every field is rendered
+ * unconditionally so `content[]` readers see the same budget detail
+ * `structuredContent` readers get. Counts are printed raw — no thousands
+ * separators — so the numbers stay greppable. (#81)
+ */
+function formatTruncation(t, lines) {
+    lines.push(`\n**Truncated (${t.mode} mode):** ${t.returnedCharacters} of ${t.originalCharacters} body characters returned across ${t.articles.length} article(s); ${t.omittedSections} section(s) omitted`);
+    const budgets = [
+        t.maxCharacters === undefined ? undefined : `maxCharacters ${t.maxCharacters}`,
+        t.maxCharactersPerSection === undefined
+            ? undefined
+            : `maxCharactersPerSection ${t.maxCharactersPerSection}`,
+    ].filter((b) => b !== undefined);
+    if (budgets.length)
+        lines.push(`Budget applied: ${budgets.join(', ')}`);
+    for (const a of t.articles) {
+        lines.push(`- ${a.id} (${a.source}): ${a.returnedCharacters} of ${a.originalCharacters} characters`);
+        for (const s of a.sections ?? []) {
+            lines.push(`  - ${s.title ?? 'untitled section'} — ${s.returnedCharacters} of ${s.originalCharacters} characters (truncated: ${s.truncated})`);
+        }
+    }
+}
+/** Per-article inline marker so a reader of one article's body knows it is partial. */
+function truncationNote(t) {
+    return `\n> Body shortened to fit the requested character budget — ${t.returnedCharacters} of ${t.originalCharacters} characters returned. See \`truncation\` for per-section counts.`;
+}
+function formatPmcArticle(a, lines, truncation) {
     lines.push(`### ${a.title ?? a.pmcId}`);
     const sourceLabel = a.viaSource === 'europepmc'
         ? `Europe PMC (structured JATS${a.epmcSource ? `, source: ${a.epmcSource}` : ''})`
@@ -1220,6 +1724,8 @@ function formatPmcArticle(a, lines) {
         lines.push(`**PubMed:** ${a.pubmedUrl}`);
     if (a.keywords?.length)
         lines.push(`**Keywords:** ${a.keywords.join(', ')}`);
+    if (truncation)
+        lines.push(truncationNote(truncation));
     if (a.abstract)
         lines.push(`\n#### Abstract\n${a.abstract}`);
     for (const sec of a.sections) {
@@ -1244,13 +1750,16 @@ function formatPmcArticle(a, lines) {
         }
     }
 }
-function formatUnpaywallArticle(a, lines) {
-    const heading = a.title ?? (a.pmid ? `PMID ${a.pmid}` : `DOI ${a.doi}`);
+function formatUnpaywallArticle(a, lines, truncation) {
+    const requestedId = a.pmcId ? `PMCID ${a.pmcId}` : a.pmid ? `PMID ${a.pmid}` : `DOI ${a.doi}`;
+    const heading = a.title ?? requestedId;
     const formatLabel = a.contentFormat === 'html-markdown'
         ? 'Unpaywall (HTML → Markdown, best-effort)'
         : 'Unpaywall (PDF → plain text)';
     lines.push(`### ${heading}`);
     lines.push(`**Source:** ${formatLabel}`);
+    if (a.pmcId)
+        lines.push(`**PMCID:** ${a.pmcId}`);
     if (a.pmid)
         lines.push(`**PMID:** ${a.pmid}`);
     lines.push(`**DOI:** ${a.doi}`);
@@ -1268,6 +1777,8 @@ function formatUnpaywallArticle(a, lines) {
     if (a.totalPages !== undefined)
         lines.push(`**Pages:** ${a.totalPages}`);
     lines.push(`\n> Section structure is not guaranteed for this source. Treat the content as best-effort raw text. OA location metadata courtesy of Unpaywall (https://unpaywall.org).`);
+    if (truncation)
+        lines.push(truncationNote(truncation));
     lines.push(`\n#### Full Text\n${a.content}`);
 }
 function formatPmcAuthor(au) {