mcp-databnf 1.0.1 → 1.1.0

package/dist/index.js

@@ -7,7 +7,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/version.ts
-var PKG_VERSION = "1.0.1";
+var PKG_VERSION = "1.1.0";
 var REPO_URL = "https://github.com/smeet666/mcp-databnf";
 
 // src/config.ts
@@ -395,8 +395,36 @@ function escapeLiteral(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, "");
 }
 var literal = (value) => `"${escapeLiteral(value)}"`;
+var INVISIBLE = /[\u0000-\u0008\u000e-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/gu;
+function withoutInvisibles(input) {
+  return input.replace(INVISIBLE, "");
+}
+function invisibleCharacters(input) {
+  const found = [];
+  for (const character of input.match(INVISIBLE) ?? []) {
+    if (!found.includes(character)) found.push(character);
+  }
+  return found;
+}
+function charactersSetAside(input) {
+  const found = [];
+  for (const character of withoutInvisibles(input).normalize("NFC")) {
+    if (/[\p{L}\p{N}'\-\s]/u.test(character) || /[‘’ʼ]/u.test(character)) continue;
+    if (!found.includes(character)) found.push(character);
+  }
+  return found;
+}
+function readSearchText(input) {
+  const words = toSearchWords(input);
+  return {
+    words,
+    terms: toIndexTerms(words),
+    invisible: invisibleCharacters(input),
+    setAside: charactersSetAside(input)
+  };
+}
 function toSearchWords(input) {
-  const cleaned = input.normalize("NFC").replace(/[‘’ʼ]/gu, "'").replace(/[^\p{L}\p{N}'-]+/gu, " ");
+  const cleaned = withoutInvisibles(input).normalize("NFC").replace(/[‘’ʼ]/gu, "'").replace(/[^\p{L}\p{N}'-]+/gu, " ");
   const words = [];
   for (const raw of cleaned.split(" ")) {
     const word = raw.replace(/^['-]+/u, "").replace(/['-]+$/u, "");
@@ -406,6 +434,15 @@ function toSearchWords(input) {
   }
   return words;
 }
+function toIndexTerms(words) {
+  const terms = [];
+  for (const word of words) {
+    for (const piece of word.split(/['-]+/u)) {
+      if (piece !== "" && !terms.includes(piece)) terms.push(piece);
+    }
+  }
+  return terms;
+}
 function containsAllWords(words) {
   if (words.length === 0) {
     throw invalidInput(
@@ -477,31 +514,47 @@ var TEXT_WINDOW = 400;
 var prefixed = (body) => `${PREFIX_BLOCK}
 ${body.trim()}
 `;
+function windowOccupancy(predicate, words) {
+  return `
+  {
+    SELECT (COUNT(*) AS ?windowRows) WHERE {
+      SELECT DISTINCT ?windowEntity ?windowText WHERE {
+        ?windowEntity ${predicate} ?windowText .
+        ?windowText bif:contains ${containsAllWords(words)} .
+      }
+      LIMIT ${TEXT_WINDOW}
+    }
+  }`;
+}
 function searchAuthorsQuery(words, limit, offset) {
   const take = boundedInteger(limit, 1, 50, "limit") + 1;
   const skip = boundedInteger(offset, 0, 5e3, "offset");
   return prefixed(`
-SELECT ?person ?name ?label ?birthYear ?deathYear ?role WHERE {
+SELECT ?person ?name ?label ?birthYear ?deathYear ?role ?windowRows WHERE {
   {
-    SELECT DISTINCT ?person WHERE {
-      {
-        SELECT DISTINCT ?person ?name WHERE {
-          ?person foaf:name ?name .
-          ?name bif:contains ${containsAllWords(words)} .
+    {
+      SELECT DISTINCT ?person WHERE {
+        {
+          SELECT DISTINCT ?person ?name WHERE {
+            ?person foaf:name ?name .
+            ?name bif:contains ${containsAllWords(words)} .
+          }
+          LIMIT ${TEXT_WINDOW}
         }
-        LIMIT ${TEXT_WINDOW}
+        ?person a foaf:Person .
       }
-      ?person a foaf:Person .
+      ORDER BY ?person
+      LIMIT ${take} OFFSET ${skip}
     }
-    ORDER BY ?person
-    LIMIT ${take} OFFSET ${skip}
+    OPTIONAL { ?person foaf:name ?name }
+    OPTIONAL { ?record foaf:focus ?person ; skos:prefLabel ?label }
+    OPTIONAL { ?person bnf:firstYear ?birthYear }
+    OPTIONAL { ?person bnf:lastYear ?deathYear }
+    OPTIONAL { ?person rdag2:biographicalInformation ?role }
   }
-  OPTIONAL { ?person foaf:name ?name }
-  OPTIONAL { ?record foaf:focus ?person ; skos:prefLabel ?label }
-  OPTIONAL { ?person bnf:firstYear ?birthYear }
-  OPTIONAL { ?person bnf:lastYear ?deathYear }
-  OPTIONAL { ?person rdag2:biographicalInformation ?role }
-}`);
+  UNION${windowOccupancy("foaf:name", words)}
+}
+ORDER BY ?person`);
 }
 var MOST_TRIPLES = 2e3;
 function authorQuery(id) {
@@ -524,29 +577,54 @@ function searchWorksQuery(words, limit, offset) {
   const take = boundedInteger(limit, 1, 50, "limit") + 1;
   const skip = boundedInteger(offset, 0, 5e3, "offset");
   return prefixed(`
-SELECT ?work ?title ?date ?status ?creator ?creatorName WHERE {
+SELECT ?work ?title ?date ?status ?creator ?creatorName ?windowRows WHERE {
   {
-    SELECT DISTINCT ?work WHERE {
-      {
-        SELECT DISTINCT ?work ?title WHERE {
-          ?work dcterms:title ?title .
-          ?title bif:contains ${containsAllWords(words)} .
+    {
+      SELECT DISTINCT ?work WHERE {
+        {
+          SELECT DISTINCT ?work ?title WHERE {
+            ?work dcterms:title ?title .
+            ?title bif:contains ${containsAllWords(words)} .
+          }
+          LIMIT ${TEXT_WINDOW}
         }
-        LIMIT ${TEXT_WINDOW}
+        ?work a rdafrbr:Work .
       }
-      ?work a rdafrbr:Work .
+      ORDER BY ?work
+      LIMIT ${take} OFFSET ${skip}
+    }
+    OPTIONAL { ?work dcterms:title ?title }
+    OPTIONAL { ?work dcterms:date ?date }
+    OPTIONAL { ?work rdae:statusOfIdentification ?status }
+    OPTIONAL {
+      ?work dcterms:creator ?creator .
+      OPTIONAL { ?creator foaf:name ?creatorName }
+    }
+  }
+  UNION${windowOccupancy("dcterms:title", words)}
+}
+ORDER BY ?work`);
+}
+function worksByCreatorQuery(id, limit, offset) {
+  const person = iriOf(id);
+  const take = boundedInteger(limit, 1, 50, "limit") + 1;
+  const skip = boundedInteger(offset, 0, 5e3, "offset");
+  return prefixed(`
+SELECT ?work ?title ?date ?year ?status ?form WHERE {
+  {
+    SELECT DISTINCT ?work WHERE {
+      ?work dcterms:creator ${person} .
     }
     ORDER BY ?work
     LIMIT ${take} OFFSET ${skip}
   }
   OPTIONAL { ?work dcterms:title ?title }
   OPTIONAL { ?work dcterms:date ?date }
+  OPTIONAL { ?work bnf:firstYear ?year }
   OPTIONAL { ?work rdae:statusOfIdentification ?status }
-  OPTIONAL {
-    ?work dcterms:creator ?creator .
-    OPTIONAL { ?creator foaf:name ?creatorName }
-  }
-}`);
+  OPTIONAL { ?work rdae:formOfWork ?form }
+}
+ORDER BY ?work`);
 }
 function workQuery(id) {
   const work = iriOf(id);
@@ -584,7 +662,8 @@ SELECT ?edition ?title ?date ?year ?publisher ?place ?editionStatement
   OPTIONAL { ?edition rdfs:seeAlso ?catalogue }
   OPTIONAL { ?edition rdarel:electronicReproduction ?reproduction }
   OPTIONAL { ?edition bnf:OCR ?ocr }
-}`);
+}
+ORDER BY ?edition`);
 }
 function digitisedForWorkQuery(id, limit) {
   const work = iriOf(id);
@@ -721,12 +800,28 @@ function toDigitisedLink(address, role, fromId, fromTitle) {
   if (!segment) return null;
   const ark = segment.split(".")[0] ?? segment;
   if (ark === "") return null;
-  return { ark, url: address, role, fromId, fromTitle };
+  return { ark, url: address, rendering: renderingOf(address, ark), role, fromId, fromTitle };
+}
+function renderingOf(address, ark) {
+  const path = address.split(/[?#]/)[0] ?? address;
+  const after = path.slice(path.indexOf(`ark:/12148/${ark}`) + `ark:/12148/${ark}`.length);
+  const rendering = after.replace(/^[./]+/, "").replace(/\/+$/, "");
+  return rendering === "" ? null : rendering;
 }
 function page(rows, limit, skipped) {
   const more = rows.length > limit;
   return skipped > 0 ? { rows: rows.slice(0, limit), hasMore: more, skipped } : { rows: rows.slice(0, limit), hasMore: more };
 }
+function readWindowOccupancy(results) {
+  for (const row of results.results.bindings) {
+    const raw = text(row.windowRows);
+    if (raw === null) continue;
+    const count = Number(raw);
+    if (Number.isInteger(count)) return count >= TEXT_WINDOW;
+  }
+  return null;
+}
+var isOccupancyRow = (row, entity) => row.windowRows !== void 0 && row[entity] === void 0;
 function byPredicate(results) {
   const index = /* @__PURE__ */ new Map();
   for (const row of results.results.bindings) {
@@ -781,6 +876,7 @@ function toAuthorSummaries(results, limit) {
   const seen = /* @__PURE__ */ new Set();
   let skipped = 0;
   for (const row of results.results.bindings) {
+    if (isOccupancyRow(row, "person")) continue;
     const iri = text(row.person);
     const id = iri === null ? null : idFromIri(iri);
     if (iri === null || id === null) {
@@ -799,7 +895,7 @@ function toAuthorSummaries(results, limit) {
       sourceUrl: publicPageFor(iri)
     });
   }
-  return page(rows, limit, skipped);
+  return { ...page(rows, limit, skipped), indexWindowFull: readWindowOccupancy(results) };
 }
 function toAuthorDetail(results, id, pageUrl) {
   const index = byPredicate(results);
@@ -863,6 +959,7 @@ function toWorkSummaries(results, limit) {
   const byId = /* @__PURE__ */ new Map();
   let skipped = 0;
   for (const row of results.results.bindings) {
+    if (isOccupancyRow(row, "work")) continue;
     const iri = text(row.work);
     const id = iri === null ? null : idFromIri(iri);
     if (iri === null || id === null) {
@@ -888,6 +985,46 @@ function toWorkSummaries(results, limit) {
       work.creators.push({ id: creatorId, name: text(row.creatorName) });
     }
   }
+  return {
+    ...page(
+      order.map((id) => byId.get(id)),
+      limit,
+      skipped
+    ),
+    indexWindowFull: readWindowOccupancy(results)
+  };
+}
+function toAuthoredWorks(results, limit) {
+  const order = [];
+  const byId = /* @__PURE__ */ new Map();
+  let skipped = 0;
+  for (const row of results.results.bindings) {
+    const iri = text(row.work);
+    const id = iri === null ? null : idFromIri(iri);
+    if (iri === null || id === null) {
+      skipped += 1;
+      continue;
+    }
+    let work = byId.get(id);
+    if (!work) {
+      work = {
+        id,
+        title: text(row.title),
+        date: text(row.date),
+        year: integer(row.year),
+        forms: [],
+        status: readStatus(text(row.status), iri),
+        sourceUrl: publicPageFor(iri)
+      };
+      byId.set(id, work);
+      order.push(id);
+    }
+    const form = text(row.form);
+    if (form !== null && form.startsWith("http")) {
+      const term = vocabularyTerm(form);
+      if (!work.forms.includes(term)) work.forms.push(term);
+    }
+  }
   return page(
     order.map((id) => byId.get(id)),
     limit,
@@ -1187,6 +1324,25 @@ var BnfClient = class {
   words(input) {
     return toSearchWords(input);
   }
+  /**
+   * The terms the index requires, which is what a row's presence rests on.
+   *
+   * The index splits inside a word at an apostrophe and at a hyphen, so a word
+   * a caller wrote as one can reach it as two, each required on its own.
+   */
+  indexTerms(words) {
+    return toIndexTerms(words);
+  }
+  /**
+   * How a piece of caller text became the terms the search was run with.
+   *
+   * A tool reports the reading back, so the same reading has to be the one the
+   * query was built from: the words, the terms the index makes of them, and
+   * the characters that reached neither.
+   */
+  searchReading(input) {
+    return readSearchText(input);
+  }
   searchAuthors(name, limit, offset) {
     const words = toSearchWords(name);
     const query = searchAuthorsQuery(words, limit, offset);
@@ -1203,7 +1359,7 @@ var BnfClient = class {
       (results) => toAuthorDetail(results, id.id, id.pageUrl)
     );
     if (!result.data.types.includes(PERSON_CLASS)) {
-      await this.refuse(id, result.data.types, "a person", "get_work reads a work.");
+      await this.refuse(id, "a person", "get_work reads a work.");
     }
     return result;
   }
@@ -1214,8 +1370,8 @@ var BnfClient = class {
    * something else are two different answers, and only one of them means the
    * caller should go looking elsewhere.
    */
-  async refuse(id, types, wanted, hint) {
-    const known = types.length > 0 ? types : (await this.read(`types:${id.id}`, kindQuery(id), toTypes)).data;
+  async refuse(id, wanted, hint) {
+    const known = (await this.read(`types:${id.id}`, kindQuery(id), toTypes)).data;
     if (known.length === 0) {
       throw notFound(`data.bnf.fr describes nothing at "${id.id}".`, {
         hint: "Find the identifier with search_authors or search_works rather than writing one.",
@@ -1245,13 +1401,26 @@ var BnfClient = class {
     if (!result.data.types.some((type) => WORK_CLASSES.has(type))) {
       await this.refuse(
         id,
-        result.data.types,
         "a work",
         "get_author reads a person, and list_editions reads the editions of a work."
       );
     }
     return result;
   }
+  /**
+   * The works one person is named the creator of.
+   *
+   * The record is not checked here. A person the catalogue credits with nothing
+   * and an address that names no person both answer with no rows, and telling
+   * them apart costs a second query that only an empty answer needs.
+   */
+  worksByAuthor(id, limit, offset) {
+    return this.read(
+      `author-works:${id.id}:${limit}:${offset}`,
+      worksByCreatorQuery(id, limit, offset),
+      (results) => toAuthoredWorks(results, limit)
+    );
+  }
   listEditions(id, limit, offset) {
     const query = editionsQuery(id, limit, offset);
     return this.read(
@@ -1354,7 +1523,12 @@ var retrievedAtSchema = z2.string().describe(
 );
 var digitisedLinkSchema = z2.object({
   ark: z2.string().describe("The Gallica ARK identifying the document."),
-  url: z2.string().describe("Open this to see the document. This server does not read it."),
+  url: z2.string().describe(
+    "The address the catalogue publishes, for a person to open. Read it beside 'rendering': an address asking for a rendering opens that view of the document rather than the document. This server does not read either."
+  ),
+  rendering: z2.string().nullable().describe(
+    "The view the address asks Gallica for, read off what follows the ARK name in it, such as 'thumbnail' for a small image or 'item' for one leaf. Null when the address names the document itself. This says what was asked for, not what comes back."
+  ),
   role: z2.enum(["reproduction", "ocr", "depiction"]).describe(
     "'reproduction' is the edition itself digitised. 'ocr' is the text a machine read off it. 'depiction' is an image illustrating the record, which can be a portrait or a page mentioning the subject rather than the work."
   ),
@@ -1394,7 +1568,33 @@ function truncate(text2, maxChars) {
   if (text2.length <= maxChars) return text2;
   return `${text2.slice(0, Math.max(0, maxChars - 1)).trimEnd()}\u2026`;
 }
-var NO_RANKING = "The full-text index answers whether a record matches, and it does not score how well. These rows are in the order the index returned them, so the row a person would call the obvious answer can sit anywhere in the list, or on a later page.";
+var WINDOW_FULL_CAVEAT = "The window this search reads off the index came back full, so records carrying these words sit past what was read and this list is a part of the matches. Which records fill a full window is settled by the index as it answers, so another reading of the same search can bring back other rows. Requiring one more word narrows the reading and reaches what a full window leaves out.";
+var WINDOW_FULL_AND_NO_MORE = "'has_more' is false because the rows of this window stop here, and the window came back full: it says where the reading stopped rather than that the catalogue holds nothing further under these words.";
+var FORMS_CAVEAT = "The codes under 'forms' are the terms of the BnF's work-form vocabulary a record points at, passed on as they stand: the vocabulary publishes no label for them here, so some read as words, such as 'roman' or 'poesi', and others, such as 'te', say nothing on their own. A work carrying no code is a work whose form the catalogue does not state.";
+var FORMS_FILTER_CAVEAT = "A form is stated on some works and left unsaid on others, so keeping the rows that carry one code finds the works declaring it and never all the works of that form.";
+var SEVERAL_RECORDS_CAVEAT = "The BnF keeps more than one authority record for some people, and a record can carry a name and nothing else while a second one carries the dates, the occupation and the works. Everything here is read off this record, so search_authors under the name will show the other records the file holds and let you compare them.";
+function readingNotes(reading, field) {
+  const notes = [];
+  const quoted = (values) => values.map((value) => `"${value}"`).join(", ");
+  if (reading.invisible.length > 0) {
+    notes.push(
+      `The text held ${reading.invisible.length} character(s) that mark nothing on a screen, such as a control character or a zero-width space. They were removed before the words were cut, so a word one of them sat inside was searched for whole rather than as two terms the index would each require.`
+    );
+  }
+  if (reading.setAside.length > 0) {
+    notes.push(
+      `Only letters and digits reach the index: ${quoted(reading.setAside)} in the text ${reading.setAside.length === 1 ? "was" : "were"} set aside, and what was searched for is ${quoted(reading.terms)}.`
+    );
+  }
+  const single = reading.terms.filter((term) => [...term].length === 1);
+  if (single.length > 0) {
+    notes.push(
+      `${quoted(single)} ${single.length === 1 ? "is a term of one character" : "are terms of one character"} and ${single.length === 1 ? "is" : "are"} required like any other: a record has to carry ${single.length === 1 ? "it" : "them"} in its ${field} for a row to be a match. Leaving ${single.length === 1 ? "it" : "them"} out widens the search.`
+    );
+  }
+  return notes;
+}
+var NO_RANKING = "The full-text index answers whether a record matches, and it does not score how well. Rows are ordered by the address of the record, which measures nothing, so the row a person would call the obvious answer can sit anywhere in the list, or on a later page. That order is the one the pages are cut along, so reading page after page reaches every match once.";
 async function classifyEmptyPage(page2, firstPageHasRow) {
   if (page2 === 1) return "absent";
   try {
@@ -1403,18 +1603,42 @@ async function classifyEmptyPage(page2, firstPageHasRow) {
     return "undetermined";
   }
 }
-var GALLICA_CAVEAT = "These are links for a person to open. This server reads the BnF catalogue and never requests gallica.bnf.fr, so it cannot say whether a document opens, what it contains, or on what terms it may be reused.";
-var PROVISIONAL_CAVEAT = "A provisional record is one the BnF created to hold a title it has catalogued and not yet established as a work of its own. Its identifier can change, and it can be merged into an established record.";
-
-// src/tools/findDigitised.ts
 var PERSON_TYPE = "http://xmlns.com/foaf/0.1/Person";
 var WORK_TYPES = [
   "http://rdvocab.info/uri/schema/FRBRentitiesRDA/Work",
   "http://rdaregistry.info/Elements/c/#C10001"
 ];
+function recordKindOf(types) {
+  if (types.includes(PERSON_TYPE)) return "person";
+  if (types.some((type) => WORK_TYPES.includes(type))) return "work";
+  return null;
+}
+function headingYears(label) {
+  const bracketed = /\(([^()]*)\)\s*$/.exec(label);
+  const [birth, death] = (bracketed?.[1] ?? "").split("-");
+  const year = (part) => part !== void 0 && /^\d{4}$/.test(part.trim()) ? Number(part.trim()) : null;
+  return { birth: year(birth), death: year(death) };
+}
+function headingYearConflicts(label, birthYear, deathYear) {
+  if (label === null) return [];
+  const stated = headingYears(label);
+  const conflicts = [];
+  if (stated.birth !== null && birthYear !== null && stated.birth !== birthYear) {
+    conflicts.push(`${stated.birth} against 'birth_year' ${birthYear}`);
+  }
+  if (stated.death !== null && deathYear !== null && stated.death !== deathYear) {
+    conflicts.push(`${stated.death} against 'death_year' ${deathYear}`);
+  }
+  return conflicts;
+}
+var GALLICA_CAVEAT = "These are links for a person to open. This server reads the BnF catalogue and never requests gallica.bnf.fr, so it cannot say whether a document opens, what it contains, or on what terms it may be reused.";
+var ALIGNMENTS_CAVEAT = "The addresses under 'same_as' are the BnF's own alignments to other files, passed on exactly as the catalogue publishes them, character for character. This server requests data.bnf.fr alone and does not open them, so it cannot say whether one still answers or what stands at the other end.";
+var PROVISIONAL_CAVEAT = "A provisional record is one the BnF created to hold a title it has catalogued and not yet established as a work of its own. Its identifier can change, and it can be merged into an established record.";
+
+// src/tools/findDigitised.ts
 var findDigitisedDescription = [
   "Gather the digitised documents the Biblioth\xE8que nationale de France catalogue attaches to one person or one work, and return them as links.",
-  "Give the identifier of either; the tool reads what kind of record it is and follows the right path. For a work it walks the editions; for a person it takes the images on the record and the digitised editions of the works they are credited with.",
+  "Give the identifier of either; the tool asks the catalogue what kind of record it is and follows the right path. For a work it walks the editions; for a person it takes the images on the record and the digitised editions of the works they are credited with. The 'kind' returned is what the catalogue types the record as.",
   "Every result is a link for someone to open. This server reads the BnF catalogue and never requests gallica.bnf.fr, so it reports nothing about what is at the other end: not whether the document opens, not what it contains, not on what terms it may be reused.",
   "It returns links and nothing else: no publisher, no date, no ISBN. Use list_editions when which edition a copy belongs to matters.",
   "A 'depiction' illustrates a record and can be a page that merely mentions the subject. A 'reproduction' is an edition digitised. An 'ocr' link names a machine-read text of a document, which this server does not fetch."
@@ -1424,7 +1648,7 @@ var findDigitisedInput = strictInput({
     "A person or work identifier, such as 'cb119219976' or 'cb11970626n'. The argument is named 'id' rather than 'work_id' or 'author_id' because it takes either."
   ),
   kind: z3.enum(["auto", "person", "work"]).default("auto").describe(
-    "Which kind of record the identifier names. 'auto' asks the catalogue, which costs one extra query."
+    "What you expect the identifier to name. The catalogue is asked either way, and a kind it contradicts is refused rather than followed. 'auto' states no expectation."
   ),
   limit: z3.number().int().min(1).max(200).default(40)
 });
@@ -1432,11 +1656,13 @@ var findDigitisedOutput = z3.object({
   id: z3.string(),
   kind: z3.enum(["person", "work"]).describe("What the catalogue types this record as."),
   links: z3.array(digitisedLinkSchema),
-  counts: z3.object({
+  links_returned_by_role: z3.object({
     reproduction: z3.number().int(),
     ocr: z3.number().int(),
     depiction: z3.number().int()
-  }).describe("Links returned on this page, by role. These count links, not documents."),
+  }).describe(
+    "How many of the links in this answer carry each role. These count the links returned here, which is neither a count of documents nor a count of what the catalogue attaches: several links can name one document, and 'has_more' says when links were left out."
+  ),
   has_more: z3.boolean(),
   retrieved_at: retrievedAtSchema,
   notes: z3.array(z3.string())
@@ -1444,43 +1670,48 @@ var findDigitisedOutput = z3.object({
 async function runFindDigitised(client, args) {
   try {
     const id = client.identify(args.id);
-    let kind;
     const notes = [];
-    if (args.kind === "auto") {
-      if (id.kind === "temp-work") {
-        kind = "work";
-      } else {
-        const types = await client.types(id);
-        if (types.data.length === 0) {
-          return toToolError(
-            notFound(`data.bnf.fr describes nothing at "${id.id}".`, {
-              hint: "Find the identifier with search_authors or search_works rather than writing one.",
+    let kind;
+    if (id.kind === "temp-work") {
+      kind = "work";
+    } else {
+      const types = await client.types(id);
+      if (types.data.length === 0) {
+        return toToolError(
+          notFound(`data.bnf.fr describes nothing at "${id.id}".`, {
+            hint: "Find the identifier with search_authors or search_works rather than writing one.",
+            url: id.pageUrl
+          })
+        );
+      }
+      const found = recordKindOf(types.data);
+      if (found === null) {
+        return toToolError(
+          notFound(
+            `"${id.id}" is described by data.bnf.fr, and it is neither a person nor a work: it is typed ${types.data.join(", ")}.`,
+            {
+              hint: "This tool follows a person or a work. For one edition, list_editions carries the digitised copies alongside the imprint.",
               url: id.pageUrl
-            })
-          );
-        }
-        if (types.data.includes(PERSON_TYPE)) kind = "person";
-        else if (types.data.some((type) => WORK_TYPES.includes(type))) kind = "work";
-        else {
-          return toToolError(
-            notFound(
-              `"${id.id}" is described by data.bnf.fr, and it is neither a person nor a work: it is typed ${types.data.join(", ")}.`,
-              {
-                hint: "This tool follows a person or a work. For one edition, list_editions carries the digitised copies alongside the imprint.",
-                url: id.pageUrl
-              }
-            )
-          );
-        }
+            }
+          )
+        );
       }
-    } else {
-      kind = args.kind;
+      kind = found;
+    }
+    if (args.kind !== "auto" && args.kind !== kind) {
+      return toToolError(
+        invalidInput(
+          `The call states that "${id.id}" is a ${args.kind}, and data.bnf.fr describes it as a ${kind}.`,
+          `Leave 'kind' out, or pass '${kind}'. Following the ${args.kind} path over a ${kind} record answers with part of the record or with none of it, and nothing in that answer would say so.`
+        )
+      );
     }
     const { data, cached, retrievedAt } = kind === "person" ? await client.digitisedForPerson(id, args.limit) : await client.digitisedForWork(id, args.limit);
     if (cached) notes.push("Served from this server's short-lived in-memory cache.");
     const links = data.rows.map((link) => ({
       ark: link.ark,
       url: link.url,
+      rendering: link.rendering,
       role: link.role,
       from_id: link.fromId,
       from_title: link.fromTitle
@@ -1490,12 +1721,18 @@ async function runFindDigitised(client, args) {
       ocr: countRole(data.rows, "ocr"),
       depiction: countRole(data.rows, "depiction")
     };
+    const rendered = links.filter((link) => link.rendering !== null);
     if (links.length > 0) notes.push(GALLICA_CAVEAT);
     if (counts.depiction > 0) {
       notes.push(
         `${counts.depiction === 1 ? "One of these is an image" : `${counts.depiction} of these are images`} the catalogue uses to illustrate the record. Such an image can be a portrait, a title page, or a newspaper page that mentions the subject in passing, and the catalogue does not say which.`
       );
     }
+    if (rendered.length > 0) {
+      notes.push(
+        `${rendered.length === 1 ? "One of these addresses opens" : `${rendered.length} of these addresses open`} a rendering of a document rather than the document: what follows the ARK name in the address, such as 'thumbnail', is the view being asked for, and 'ark' names the document that view was taken from. Read 'rendering' before quoting a link as the document itself.`
+      );
+    }
     if (counts.ocr > 0) {
       notes.push(
         `${counts.ocr === 1 ? "One of these points" : `${counts.ocr} of these point`} at a text a machine read off a scanned document. This server names that text and does not read it.`
@@ -1505,6 +1742,9 @@ async function runFindDigitised(client, args) {
       notes.push(
         args.limit >= 200 ? "The catalogue points at more documents than this tool will return in one answer, and it does not page: 200 is the ceiling. Read the editions with list_editions to reach the rest, one page at a time." : `More links exist than were returned. Raise 'limit' to see more of them, up to 200. This tool does not page, so a higher limit re-reads the links already shown rather than continuing after them.`
       );
+      notes.push(
+        "The figures under 'links_returned_by_role' count the links in this answer, so they fall short of what the catalogue attaches by however much was left out."
+      );
     }
     if (links.length === 0) {
       notes.push(
@@ -1521,7 +1761,7 @@ ${links.map((link, index) => {
         id: id.id,
         kind,
         links,
-        counts,
+        links_returned_by_role: counts,
         has_more: data.hasMore,
         retrieved_at: retrievedAt,
         notes
@@ -1541,7 +1781,7 @@ var getAuthorDescription = [
   "Read one person's record in the Biblioth\xE8que nationale de France authority file, by the identifier search_authors returns.",
   "It carries the dates and places of birth and death, the occupation the record names, the language and country it associates with the person, the field of activity with its Dewey class, and the addresses for the same person in VIAF, IdRef, DBpedia, Wikidata and ISNI.",
   "It carries no biography. The field the BnF calls biographical information is a job title on most records and a single word on many, so quote it as what the catalogue states and do not build a life story out of it.",
-  "It does not list the person's works. The catalogue links them, and no tool here walks that link: search_works reads titles, so a work is found by its title rather than by its author.",
+  "It lists no work. list_works walks from this record to the works the catalogue names the person the creator of, and states what that link does and does not reach.",
   "'depictions' are images data.bnf.fr attaches to the person. They are links for a person to open; this server does not read them, and an image can be a page that mentions the person rather than a portrait of them."
 ].join(" ");
 var getAuthorInput = strictInput({
@@ -1575,7 +1815,9 @@ var getAuthorOutput = z4.object({
     fields: z4.array(z4.string()).describe("Fields of activity in the words of the record."),
     dewey_classes: z4.array(z4.string()).describe("Dewey classes the fields point at, such as '800' for literature."),
     same_as: z4.record(z4.string(), z4.array(z4.string())).describe("Addresses for the same person in other files, grouped by file."),
-    catalogue_url: z4.string().nullable().describe("The record in the BnF general catalogue."),
+    catalogue_url: z4.string().nullable().describe(
+      "The address of this record in the BnF general catalogue, as the record itself points at it. Null when the record states none, which is a silence in the record rather than a record the general catalogue lacks: no address is built in its place."
+    ),
     record_created: z4.string().nullable().describe("When the authority record was created."),
     record_modified: z4.string().nullable().describe("When it was last changed."),
     source_url: z4.string()
@@ -1598,17 +1840,36 @@ async function runGetAuthor(client, args) {
         `The BnF states "${data.biographicalInformation}" as this person's biographical information. That field holds an occupation rather than a life, and this is all the catalogue says.`
       );
     }
+    if (data.biographicalInformation !== null && data.biographicalInformation === data.occupation) {
+      notes.push(
+        "This record states the same text under 'biographical_information' and 'occupation', character for character. It is one statement written in two fields rather than two the record makes separately."
+      );
+    }
+    const headings = [data.label, ...data.otherNames.map((other) => other.label)];
+    const conflicts = [
+      ...new Set(
+        headings.flatMap(
+          (heading) => headingYearConflicts(heading, data.birthYear, data.deathYear)
+        )
+      )
+    ];
+    if (conflicts.length > 0) {
+      notes.push(
+        `This record states its dates twice and the two disagree: the heading says ${conflicts.join(", and ")}. Both are passed on as the BnF publishes them, and the record says nothing about which is right, so read source_url before citing either.`
+      );
+    }
     if (data.deathDate === null && data.deathYear === null) {
+      const dated = data.birthDate !== null || data.birthYear !== null;
       notes.push(
-        "The record states no date of death. That can mean the person is living, or that the BnF has not recorded one; the catalogue does not distinguish the two."
+        dated ? "The record states no date of death. That can mean the person is living, or that the BnF has not recorded one; the catalogue does not distinguish the two." : `This record states no date of birth and no date of death, so it dates the person nowhere and says nothing about whether they are living. ${SEVERAL_RECORDS_CAVEAT}`
       );
     }
     if (Object.keys(data.sameAs).length > 0) {
       notes.push(
-        "The addresses under 'same_as' are the BnF's own alignments to other files. Following one is how to reach a biography, which this catalogue does not hold."
+        `${ALIGNMENTS_CAVEAT} Following one is how to reach a biography, which this catalogue does not hold.`
       );
     }
-    if (data.depictions.length > 0) notes.push(GALLICA_CAVEAT);
+    if (args.include_depictions && data.depictions.length > 0) notes.push(GALLICA_CAVEAT);
     const structured = {
       author: {
         id: data.id,
@@ -1643,6 +1904,7 @@ async function runGetAuthor(client, args) {
       structured.depictions = data.depictions.map((link) => ({
         ark: link.ark,
         url: link.url,
+        rendering: link.rendering,
         role: link.role,
         from_id: link.fromId,
         from_title: link.fromTitle
@@ -1680,6 +1942,7 @@ import { z as z5 } from "zod";
 var getWorkDescription = [
   "Read one work's record in the Biblioth\xE8que nationale de France catalogue, by the identifier search_works returns.",
   "It carries the title, everyone the record credits, the date the BnF gives the work, its language, its form and its subject with the Dewey class.",
+  "'forms' holds the work-form vocabulary's own terms, which carry no label in this dataset, so some read as words and some do not. A record stating none has a form the catalogue does not state.",
   "'status' says whether the record is established or provisional, and 'status_statement' repeats what the catalogue itself states. A provisional identifier can change, so cite an established one where there is a choice.",
   "'expression_count' counts the expressions the record links, which is not a count of published editions: use list_editions for those."
 ].join(" ");
@@ -1700,7 +1963,9 @@ var getWorkOutput = z5.object({
     first_year: z5.number().int().nullable(),
     creators: z5.array(z5.object({ id: z5.string(), name: z5.string().nullable() })),
     languages: z5.array(z5.string()).describe("ISO 639-2 codes."),
-    forms: z5.array(z5.string()).describe("Forms from the BnF work-form vocabulary, such as 'poesi' for poetry."),
+    forms: z5.array(z5.string()).describe(
+      "Terms of the BnF work-form vocabulary, as the terms themselves. The vocabulary publishes no label for them here, so they are not translated: some read as words, such as 'poesi', and some do not, such as 'te'. An empty list is a form the record does not state."
+    ),
     subjects: z5.array(z5.string()).describe("Subjects in the words of the record."),
     dewey_classes: z5.array(z5.string()),
     status: z5.enum(["established", "provisional"]),
@@ -1709,7 +1974,9 @@ var getWorkOutput = z5.object({
       "Expressions the record links: translations, adaptations, recordings. This is not a count of published editions. Null when the record was longer than one query reads, since the number would then be the ceiling rather than the count."
     ),
     same_as: z5.record(z5.string(), z5.array(z5.string())),
-    catalogue_url: z5.string().nullable(),
+    catalogue_url: z5.string().nullable().describe(
+      "The address of this record in the BnF general catalogue, as the record itself points at it. Null when the record states none, which is the ordinary case on work records: it is a silence in the record rather than a record the general catalogue lacks, and no address is built in its place."
+    ),
     source_url: z5.string()
   }),
   depictions: z5.array(digitisedLinkSchema).optional(),
@@ -1744,12 +2011,14 @@ async function runGetWork(client, args) {
         `The record links ${data.expressionCount} expression(s): translations, adaptations and recordings of this work. Published editions are a separate count, and list_editions is what reads them.`
       );
     }
+    if (data.forms.length > 0) notes.push(FORMS_CAVEAT);
     if (data.creators.length === 0) {
       notes.push(
         "The record credits nobody with this work. That is normal for anonymous and traditional works, and it also happens on records a cataloguer has not finished."
       );
     }
-    if (data.depictions.length > 0) notes.push(GALLICA_CAVEAT);
+    if (Object.keys(data.sameAs).length > 0) notes.push(ALIGNMENTS_CAVEAT);
+    if (args.include_depictions && data.depictions.length > 0) notes.push(GALLICA_CAVEAT);
     const structured = {
       work: {
         id: data.id,
@@ -1777,6 +2046,7 @@ async function runGetWork(client, args) {
       structured.depictions = data.depictions.map((link) => ({
         ark: link.ark,
         url: link.url,
+        rendering: link.rendering,
         role: link.role,
         from_id: link.fromId,
         from_title: link.fromTitle
@@ -1803,7 +2073,7 @@ var listEditionsDescription = [
   "List the published editions of one work in the Biblioth\xE8que nationale de France catalogue, by the identifier search_works or get_work returns.",
   "Each row carries the publisher, the place, the year, the edition statement, the extent in the words of the record, the ISBN when there is one, and the record in the BnF general catalogue.",
   "An edition that has been digitised carries a link under 'digitised'. That link says a copy exists at that address; this server never opens it, so it cannot say whether the document is readable, complete, or free to reuse.",
-  "Rows are in the order the catalogue holds them, which is neither by date nor by importance."
+  "Rows are ordered by the address the catalogue gives each edition, which is neither by date nor by importance."
 ].join(" ");
 var listEditionsInput = strictInput({
   work_id: z6.string().min(1).max(200).describe("The work identifier, such as 'cb11970626n'."),
@@ -1815,8 +2085,12 @@ var editionRowSchema = z6.object({
   title: z6.string().nullable().describe("The title as this edition carries it."),
   date: z6.string().nullable().describe("The date as published, which can be a phrase such as '[s.d.]' for an undated one."),
   year: z6.number().int().nullable().describe("The year, when the record states one as a number."),
-  publisher: z6.string().nullable(),
-  place: z6.string().nullable(),
+  publisher: z6.string().nullable().describe(
+    "The publisher as the record writes it, square brackets included. A bracketed part is the cataloguer speaking rather than the item: '[s.n.]' is a publisher the item does not name, and a role such as '[\xE9d., distrib.]' is what the named house did rather than part of its name."
+  ),
+  place: z6.string().nullable().describe(
+    "The place of publication as the record writes it, square brackets included. '[Paris]' is a place the cataloguer supplied because the item does not print one, and '[S.l.]' is an item stating no place at all."
+  ),
   edition_statement: z6.string().nullable().describe("Such as a numbered or revised edition."),
   extent: z6.string().nullable().describe("The extent in the words of the record: pages, volumes, discs."),
   isbn: z6.string().nullable(),
@@ -1858,6 +2132,7 @@ async function runListEditions(client, args) {
       digitised: row.digitised.map((link) => ({
         ark: link.ark,
         url: link.url,
+        rendering: link.rendering,
         role: link.role,
         from_id: link.fromId,
         from_title: link.fromTitle
@@ -1866,6 +2141,14 @@ async function runListEditions(client, args) {
     }));
     const digitisedCount = editions.filter((edition) => edition.digitised.length > 0).length;
     if (digitisedCount > 0) notes.push(GALLICA_CAVEAT);
+    const bracketed = editions.some(
+      (edition) => (edition.publisher?.includes("[") ?? false) || (edition.place?.includes("[") ?? false)
+    );
+    if (bracketed) {
+      notes.push(
+        "Square brackets in 'place' and 'publisher' are the cataloguer's own, kept as the record writes them: '[S.l.]' and '[s.n.]' are an item naming no place and no publisher, a bracketed name is one supplied from outside the item, and a bracketed role such as '[\xE9d., distrib.]' says what a named house did. Drop them before quoting a value as what the item prints."
+      );
+    }
     if (data.hasMore) {
       notes.push(`More editions exist beyond this page. Ask for page ${args.page + 1}.`);
     }
@@ -1874,13 +2157,14 @@ async function runListEditions(client, args) {
         `Page ${args.page} holds no row, which means the list ended earlier rather than that the work has no editions. Ask for page 1 to see it from the start.`
       );
     } else if (editions.length === 0) {
+      await assertWork(client, id);
       notes.push(
         `The catalogue links no published edition to "${id.id}". A work record can exist with none: it happens on provisional records, and on works the BnF describes through an anthology rather than through an edition of their own. Check get_work to see what kind of record this is.`
       );
     }
     if (editions.length > 0) {
       notes.push(
-        "Rows are in the order the catalogue holds them. It is neither chronological nor an order of importance, so a first edition can appear anywhere in the list."
+        "Rows are ordered by the address the catalogue gives each edition. It is neither chronological nor an order of importance, so a first edition can appear anywhere in the list. That order is the one the pages are cut along, so reading page after page reaches every edition once."
       );
     }
     const body = editions.length === 0 ? args.page > 1 ? `Page ${args.page} of the editions of "${id.id}" holds no row.` : `The BnF catalogue links no edition to the work "${id.id}".` : `${editions.length} edition(s) of "${id.id}":
@@ -1914,57 +2198,237 @@ ${editions.map((edition, index) => {
     return toToolError(error);
   }
 }
+async function assertWork(client, id) {
+  if (id.kind === "temp-work") return;
+  const types = await client.types(id);
+  if (types.data.length === 0) {
+    throw notFound(`data.bnf.fr describes nothing at "${id.id}".`, {
+      hint: "Find the identifier with search_works, or with list_works for the works of one person.",
+      url: id.pageUrl
+    });
+  }
+  if (recordKindOf(types.data) !== "work") {
+    throw notFound(
+      `"${id.id}" is described by data.bnf.fr, and it is not a work: it is typed ${types.data.join(", ")}.`,
+      {
+        hint: "This tool reads the editions of a work. For a person, list_works reaches the works they are credited with and get_author reads their record.",
+        url: id.pageUrl
+      }
+    );
+  }
+}
 
-// src/tools/searchAuthors.ts
+// src/tools/listWorks.ts
 import { z as z7 } from "zod";
+var PERSON_TYPE2 = "http://xmlns.com/foaf/0.1/Person";
+var SCOPE = "A work is on this list because the BnF catalogue names this person as the creator of it. That is one link in the catalogue and not a bibliography: the catalogue credits a person on a record in other ways, and the BnF holds printed editions whose work it has never established as a record of its own.";
+var DATE_CAVEAT = "'date' and 'year' are the date of the work as the record gives it, which dates the work rather than any printing of it. A provisional record is made from a title the BnF has catalogued, so its date can be that of the printing it was made from. For the year a copy was printed, read list_editions.";
+var ORDER_CAVEAT = "Rows are ordered by the address the catalogue gives each work, which is neither chronological nor an order of importance, so a first work can appear anywhere in the list. That order is the one the pages are cut along, so reading page after page reaches every work once.";
+var listWorksDescription = [
+  "List the works the Biblioth\xE8que nationale de France catalogue names one person the creator of, by the identifier search_authors returns. This is the tool for 'what did this person write'.",
+  "Each row carries the title, the date the record gives the work, the form codes the catalogue points at, whether the record is established or provisional, and the identifier get_work, list_editions and find_digitised take.",
+  "It is not a bibliography. It reports one link the catalogue holds, and the catalogue credits a person on a record in other ways and holds editions whose work it has never established, so a work missing here is not a work the person did not write.",
+  "The form codes are the work-form vocabulary's own terms and carry no label in this dataset, so some read as words and some do not. A work stating no code has a form the catalogue does not state, so keeping the rows carrying one code finds the works that declare it and never all the works of that form.",
+  "Rows are ordered by the address the catalogue gives each work, which is neither chronological nor an order of importance. No total is reported, because the catalogue counts nothing here and a count would read as a measure of what the person wrote."
+].join(" ");
+var listWorksInput = strictInput({
+  author_id: z7.string().min(1).max(200).describe(
+    "The person identifier from search_authors, such as 'cb119219976'. A full data.bnf.fr address is accepted too."
+  ),
+  limit: z7.number().int().min(1).max(50).default(10),
+  page: z7.number().int().min(1).max(100).default(1)
+});
+var authoredWorkRowSchema = z7.object({
+  id: z7.string().describe("Pass this to get_work, list_editions or find_digitised."),
+  title: z7.string().nullable(),
+  date: z7.string().nullable().describe(
+    "The date the record gives the work, as published. It dates the work rather than an edition of it."
+  ),
+  year: z7.number().int().nullable().describe("The same date as a number, when the record has one."),
+  forms: z7.array(z7.string()).describe(
+    "Terms of the BnF work-form vocabulary, as the terms themselves. The vocabulary publishes no label for them here, so they are not translated: some read as words, such as 'roman', and some do not, such as 'te'. An empty list is a form the record does not state, not a work without one."
+  ),
+  status: z7.enum(["established", "provisional"]).describe(
+    "'established' is a work the BnF has settled as a record of its own. 'provisional' is a title it holds while a cataloguer settles it, whose identifier can change."
+  ),
+  source_url: z7.string()
+});
+var listWorksOutput = z7.object({
+  author_id: z7.string(),
+  works: z7.array(authoredWorkRowSchema),
+  page: z7.number().int(),
+  has_more: z7.boolean(),
+  retrieved_at: retrievedAtSchema,
+  notes: z7.array(z7.string())
+});
+function emptyPageNote(emptiness, page2, authorId) {
+  if (emptiness === "past_the_end") {
+    return `Page ${page2} holds no row because it sits past the last row of this listing. The catalogue does link works to "${authorId}", and they are on earlier pages: call again with page=1, or with a lower page number, to read them.`;
+  }
+  if (emptiness === "undetermined") {
+    return `Page ${page2} holds no row, and the first page of the same listing could not be read to find out why. This is either the catalogue linking no work to "${authorId}", or a page sitting past the last row of a listing that does hold some. Call again with page=1: rows there mean the second.`;
+  }
+  return `The BnF catalogue links no work to "${authorId}" as its creator. The record exists and this link is empty on it, which is a statement about the catalogue rather than about what the person wrote. ${SEVERAL_RECORDS_CAVEAT}`;
+}
+function emptyPageBody(emptiness, page2, authorId) {
+  if (emptiness === "past_the_end") {
+    return `Page ${page2} of the works linked to "${authorId}" holds no row: it sits past the last row. Call again with page=1.`;
+  }
+  if (emptiness === "undetermined") {
+    return `Page ${page2} of the works linked to "${authorId}" holds no row, and whether the rows stop before it could not be read. Call again with page=1.`;
+  }
+  return `The BnF catalogue links no work to "${authorId}" as its creator.`;
+}
+async function runListWorks(client, args) {
+  try {
+    const id = client.identify(args.author_id);
+    const offset = (args.page - 1) * args.limit;
+    const { data, cached, retrievedAt } = await client.worksByAuthor(id, args.limit, offset);
+    const notes = [];
+    if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    const works = data.rows.map((row) => ({
+      id: row.id,
+      title: row.title,
+      date: row.date,
+      year: row.year,
+      forms: row.forms,
+      status: row.status,
+      source_url: row.sourceUrl
+    }));
+    notes.push(SCOPE);
+    if (data.skipped !== void 0 && data.skipped > 0) {
+      notes.push(
+        `${data.skipped} row(s) the endpoint sent could not be read, because each named a record at an address this client cannot address. The page is short by that much rather than the catalogue holding less.`
+      );
+    }
+    let emptiness = "absent";
+    if (works.length === 0) {
+      emptiness = await classifyEmptyPage(args.page, async () => {
+        const first = await client.worksByAuthor(id, 1, 0);
+        return first.data.rows.length > 0;
+      });
+      if (emptiness === "absent") await assertPerson(client, id);
+      notes.push(emptyPageNote(emptiness, args.page, id.id));
+    } else {
+      if (data.hasMore) {
+        notes.push(
+          `More works exist beyond this page. Ask for page ${args.page + 1}. This server reports no total: a count of the works one link reaches would read as a count of what the person wrote, and the catalogue does not carry that.`
+        );
+      }
+      notes.push(`${FORMS_CAVEAT} ${FORMS_FILTER_CAVEAT}`);
+      if (works.some((work) => work.status === "provisional")) notes.push(PROVISIONAL_CAVEAT);
+      notes.push(ORDER_CAVEAT, DATE_CAVEAT);
+    }
+    const body = works.length === 0 ? emptyPageBody(emptiness, args.page, id.id) : `${works.length} work(s) the catalogue links to "${id.id}" as their creator:
+${works.map((work, index) => {
+      const when = work.date ? ` (${work.date})` : "";
+      const forms = work.forms.length > 0 ? ` \xB7 form: ${work.forms.join(", ")}` : "";
+      const status = work.status === "provisional" ? " \xB7 provisional record" : "";
+      return `${index + 1}. ${work.title ?? work.id}${when}${forms}${status} \xB7 id: ${work.id}
+   ${work.source_url}`;
+    }).join("\n")}`;
+    return ok(
+      {
+        author_id: id.id,
+        works,
+        page: args.page,
+        has_more: data.hasMore,
+        retrieved_at: retrievedAt,
+        notes
+      },
+      body,
+      { retrievedAt, notes, sourceUrl: id.pageUrl }
+    );
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+async function assertPerson(client, id) {
+  const types = await client.types(id);
+  if (types.data.length === 0) {
+    throw notFound(`data.bnf.fr describes nothing at "${id.id}".`, {
+      hint: "Find the identifier with search_authors rather than writing one.",
+      url: id.pageUrl
+    });
+  }
+  if (!types.data.includes(PERSON_TYPE2)) {
+    throw notFound(
+      `"${id.id}" is described by data.bnf.fr, and it is not a person: it is typed ${types.data.join(", ")}.`,
+      {
+        hint: "This tool walks from a person to the works they are credited with. For a work, list_editions reads its editions and get_work reads the record.",
+        url: id.pageUrl
+      }
+    );
+  }
+}
+
+// src/tools/searchAuthors.ts
+import { z as z8 } from "zod";
 var searchAuthorsDescription = [
   "Find a person in the Biblioth\xE8que nationale de France authority file by name, and get the identifier the other tools take.",
   "This matches the name the BnF records, so it takes a surname, a full name or both names in either order. It does not read biographies, so it cannot find a person from what they wrote or what they did.",
+  "It reads the person records and nothing else: an organisation, a conference or a place is outside it, and an answer holding no row says nothing about those.",
+  "The match is letter for letter, so a name written with other accents or under another transliteration is a different search: try the spellings a library would use before concluding the BnF holds nobody of that name.",
   "Several rows can carry one name: the BnF keeps more than one authority record for some people, and many people share a name. Read 'birth_year', 'death_year' and 'role' to tell them apart, and show the caller the choice rather than picking one.",
-  "Rows come back in the order the index returned them, which is not an order of relevance."
+  "Rows come back ordered by the address of the record, which is not an order of relevance. That order is the one the pages are cut along, so paging through a search reaches every match once.",
+  "One search reads a fixed window of the index. 'index_window_full' says whether that window came back full: when it did, names sit past what was read, 'has_more' being false says where the reading stopped, and another reading of the same search can bring back other rows. Narrow the name to reach further."
 ].join(" ");
 var searchAuthorsInput = strictInput({
-  name: z7.string().min(1).max(200).describe("The person's name, such as 'Rimbaud' or 'Arthur Rimbaud'."),
-  limit: z7.number().int().min(1).max(50).default(10),
-  page: z7.number().int().min(1).max(100).default(1)
+  name: z8.string().min(1).max(200).describe("The person's name, such as 'Rimbaud' or 'Arthur Rimbaud'."),
+  limit: z8.number().int().min(1).max(50).default(10),
+  page: z8.number().int().min(1).max(100).default(1)
 });
-var authorRowSchema = z7.object({
-  id: z7.string().describe("Pass this to get_author, or to find_digitised."),
-  name: z7.string().nullable().describe("The name as data.bnf.fr writes it."),
-  label: z7.string().nullable().describe("The authority heading, which usually carries the dates in brackets."),
-  birth_year: z7.number().int().nullable(),
-  death_year: z7.number().int().nullable().describe("Null when the record states none."),
-  role: z7.string().nullable().describe(
+var authorRowSchema = z8.object({
+  id: z8.string().describe("Pass this to get_author, or to find_digitised."),
+  name: z8.string().nullable().describe("The name as data.bnf.fr writes it."),
+  label: z8.string().nullable().describe("The authority heading, which usually carries the dates in brackets."),
+  birth_year: z8.number().int().nullable(),
+  death_year: z8.number().int().nullable().describe("Null when the record states none."),
+  role: z8.string().nullable().describe(
     "What the record says the person did. This field holds a job title far more often than a sentence, and is frequently a single word."
   ),
-  source_url: z7.string().describe("The record's page. Show this when citing it.")
+  source_url: z8.string().describe("The record's page. Show this when citing it.")
 });
-var searchAuthorsOutput = z7.object({
-  name: z7.string().describe("The name asked for."),
-  words_searched: z7.array(z7.string()).describe("The words the index was actually asked for, after punctuation was set aside."),
-  authors: z7.array(authorRowSchema),
-  page: z7.number().int(),
-  has_more: z7.boolean().describe("Whether the index held at least one further match beyond this page."),
+var searchAuthorsOutput = z8.object({
+  name: z8.string().describe("The name asked for."),
+  words_searched: z8.array(z8.string()).describe(
+    "The terms the index required, each of which has to appear in the name. A word is cut at an apostrophe and at a hyphen before the index sees it, so a name written as one word can appear here as two, and a record carrying the pieces apart is a match."
+  ),
+  authors: z8.array(authorRowSchema),
+  page: z8.number().int(),
+  has_more: z8.boolean().describe(
+    "Whether the endpoint held at least one further row beyond this page, within the window the search read off the index. Read it alongside 'index_window_full': false on a full window says where the reading stopped rather than that the file holds nobody else."
+  ),
+  index_window_full: z8.boolean().nullable().describe(
+    "Whether the fixed window this search reads off the index came back full. True means records carrying these words sit past what was read, so the rows here are a part of the matches and another reading can bring back other rows. False means the window held everything that matched. Null when the endpoint stated no occupancy, which claims nothing either way."
+  ),
   retrieved_at: retrievedAtSchema,
-  notes: z7.array(z7.string())
+  notes: z8.array(z8.string())
 });
+var SPELLING_CAVEAT = "The index matches the words letter for letter, so a name written with other accents, or under another transliteration, is a different search reaching different records. A short answer is no evidence that the file holds nobody else of that name: ask again with the accents dropped, with them restored, and under the transliterations a library uses.";
 function lifespan(birthYear, deathYear) {
   if (birthYear !== null && deathYear !== null) return ` (${birthYear}\u2013${deathYear})`;
   if (birthYear !== null) return ` (born ${birthYear})`;
   if (deathYear !== null) return ` (died ${deathYear})`;
   return "";
 }
-function emptyPageNote(emptiness, page2, words) {
+function emptyPageNote2(emptiness, page2, words, windowFull) {
   const quoted = words.map((word) => `"${word}"`).join(", ");
+  if (windowFull) {
+    return `The window this search reads off the index came back full, and no person record survived the reading: every row of it named something the authority file types as another kind of heading. Whether a person carries ${quoted} in a name is unanswered here rather than answered no. Narrow the search, by adding a word or by writing a fuller form of the name, so that the window reaches further into the index.`;
+  }
   if (emptiness === "past_the_end") {
     return `Page ${page2} holds no row because it sits past the last row of this search. Records do carry ${quoted} in a name, and they are on earlier pages: call again with page=1, or with a lower page number, to read them.`;
   }
   if (emptiness === "undetermined") {
     return `Page ${page2} holds no row, and reading the first page of the same search to find out why did not answer. This is either a name carrying ${quoted} matching no record, or a page sitting past the last row of a search that does match. Call again with page=1: rows there mean the second.`;
   }
-  return `No record in the BnF authority file carries every one of these words in a name: ${quoted}. A search here reads names, so a person known by a pen name is found under that name rather than their own.`;
+  return `No person record in the BnF authority file carries every one of these words in a name: ${quoted}. This search reads the person records and nothing else, so an organisation, a conference, a place or a subject heading is outside what was looked at, whether or not the BnF holds a heading for one. It reads names, so a person known by a pen name is found under that name rather than their own.`;
 }
-function emptyPageBody(emptiness, page2, name) {
+function emptyPageBody2(emptiness, page2, name, windowFull) {
+  if (windowFull) {
+    return `No person record survived the reading for "${name}", out of a window of the index that came back full. Narrow the search.`;
+  }
   if (emptiness === "past_the_end") {
     return `Page ${page2} of the search for "${name}" holds no row: it sits past the last row. Call again with page=1.`;
   }
@@ -1975,7 +2439,8 @@ function emptyPageBody(emptiness, page2, name) {
 }
 async function runSearchAuthors(client, args) {
   try {
-    const words = client.words(args.name);
+    const reading = client.searchReading(args.name);
+    const words = reading.words;
     if (words.length === 0) {
       return toToolError(
         invalidInput(
@@ -1994,8 +2459,21 @@ async function runSearchAuthors(client, args) {
       );
     }
     const { data, cached, retrievedAt } = await client.searchAuthors(args.name, args.limit, offset);
+    const terms = reading.terms;
+    const windowFull = data.indexWindowFull ?? null;
     const notes = [];
     if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (windowFull) {
+      notes.push(WINDOW_FULL_CAVEAT);
+      if (!data.hasMore) notes.push(WINDOW_FULL_AND_NO_MORE);
+    }
+    const split = words.filter((word) => /['-]/u.test(word));
+    if (split.length > 0) {
+      notes.push(
+        `${split.map((word) => `"${word}"`).join(", ")} reached the index as separate terms: it cuts a word at an apostrophe and at a hyphen, and requires each piece to appear in the name rather than in that arrangement, so a record writing the pieces apart is a match.`
+      );
+    }
+    notes.push(...readingNotes(reading, "name"));
     const authors = data.rows.map((row) => ({
       id: row.id,
       name: row.name,
@@ -2006,6 +2484,16 @@ async function runSearchAuthors(client, args) {
       source_url: row.sourceUrl
     }));
     if (authors.length > 0) notes.push(NO_RANKING);
+    notes.push(SPELLING_CAVEAT);
+    const disputed = authors.map((author) => ({
+      label: author.label ?? author.name,
+      conflicts: headingYearConflicts(author.label, author.birth_year, author.death_year)
+    })).filter((row) => row.conflicts.length > 0);
+    if (disputed.length > 0) {
+      notes.push(
+        `${disputed.map((row) => `"${row.label}" states ${row.conflicts.join(", and ")}`).join("; ")}. A record stating its dates twice can disagree with itself, and the BnF publishes both. These fields are what tells two people of one name apart, so open source_url before telling them apart by a date the record disputes.`
+      );
+    }
     const repeated = /* @__PURE__ */ new Map();
     for (const author of authors) {
       const key = (author.name ?? "").toLocaleLowerCase("fr");
@@ -2024,18 +2512,13 @@ async function runSearchAuthors(client, args) {
     }
     let emptiness = "absent";
     if (authors.length === 0) {
-      emptiness = await classifyEmptyPage(args.page, async () => {
+      emptiness = windowFull ? "absent" : await classifyEmptyPage(args.page, async () => {
         const first = await client.searchAuthors(args.name, 1, 0);
         return first.data.rows.length > 0;
       });
-      notes.push(emptyPageNote(emptiness, args.page, words));
+      notes.push(emptyPageNote2(emptiness, args.page, terms, windowFull === true));
     }
-    if (words.length < args.name.trim().split(/\s+/).length) {
-      notes.push(
-        `The index was asked for ${words.map((word) => `"${word}"`).join(", ")}; anything in the name that was not a word was set aside.`
-      );
-    }
-    const body = authors.length === 0 ? emptyPageBody(emptiness, args.page, args.name) : `${authors.length} record(s) for "${args.name}":
+    const body = authors.length === 0 ? emptyPageBody2(emptiness, args.page, args.name, windowFull === true) : `${authors.length} record(s) for "${args.name}":
 ${authors.map((author, index) => {
       const life = lifespan(author.birth_year, author.death_year);
       const role = author.role ? ` \xB7 ${author.role}` : "";
@@ -2045,10 +2528,11 @@ ${authors.map((author, index) => {
     return ok(
       {
         name: args.name,
-        words_searched: words,
+        words_searched: terms,
         authors,
         page: args.page,
         has_more: data.hasMore,
+        index_window_full: windowFull,
         retrieved_at: retrievedAt,
         notes
       },
@@ -2061,40 +2545,51 @@ ${authors.map((author, index) => {
 }
 
 // src/tools/searchWorks.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var searchWorksDescription = [
   "Find a work in the Biblioth\xE8que nationale de France catalogue by words in its title, and get the identifier get_work and list_editions take.",
-  "A row matches when its title carries every word given. The index returns no measure of how well a row matches, so the rows are in index order and the work a person would call the obvious answer can sit anywhere in the list or on a later page.",
+  "A row matches when its title carries every word given. The index returns no measure of how well a row matches, so the rows are ordered by the address of the record and the work a person would call the obvious answer can sit anywhere in the list or on a later page.",
   "A study of a book carries the book's title, so a search for a famous title returns the criticism alongside the work. Read 'creators' to tell them apart.",
-  "This reads titles and nothing else. It cannot find the works of a named person: searching a person's name returns works written about them, whose creators are their critics.",
-  "'status' says whether the BnF has established the work as a record of its own or holds it provisionally under a title it has catalogued."
+  "This reads titles and nothing else. Searching a person's name returns the works written about them, whose creators are their critics; list_works is what walks from a person to the works the catalogue names them the creator of.",
+  "'status' says whether the BnF has established the work as a record of its own or holds it provisionally under a title it has catalogued.",
+  "One search reads a fixed window of the index, and that window is read before the works are told apart from everything else the index holds, so even a short list can rest on a full one. 'index_window_full' says which: when it is true, titles sit past what was read, 'has_more' being false says where the reading stopped, and another reading of the same search can bring back other rows. Add a word to the title to reach further."
 ].join(" ");
 var searchWorksInput = strictInput({
-  title: z8.string().min(1).max(200).describe("Words from the title, such as 'saison enfer'. Every word given has to appear."),
-  limit: z8.number().int().min(1).max(50).default(10),
-  page: z8.number().int().min(1).max(100).default(1)
+  title: z9.string().min(1).max(200).describe("Words from the title, such as 'saison enfer'. Every word given has to appear."),
+  limit: z9.number().int().min(1).max(50).default(10),
+  page: z9.number().int().min(1).max(100).default(1)
 });
-var workRowSchema = z8.object({
-  id: z8.string().describe("Pass this to get_work, list_editions or find_digitised."),
-  title: z8.string().nullable(),
-  date: z8.string().nullable().describe("The year the record gives the work, as published."),
-  creators: z8.array(z8.object({ id: z8.string(), name: z8.string().nullable() })).describe("Everyone the record credits. Empty when the record credits nobody."),
-  status: z8.enum(["established", "provisional"]).describe(
+var workRowSchema = z9.object({
+  id: z9.string().describe("Pass this to get_work, list_editions or find_digitised."),
+  title: z9.string().nullable(),
+  date: z9.string().nullable().describe("The year the record gives the work, as published."),
+  creators: z9.array(z9.object({ id: z9.string(), name: z9.string().nullable() })).describe("Everyone the record credits. Empty when the record credits nobody."),
+  status: z9.enum(["established", "provisional"]).describe(
     "'established' is a work the BnF has settled as a record of its own. 'provisional' is a title it holds while a cataloguer settles it, whose identifier can change."
   ),
-  source_url: z8.string()
+  source_url: z9.string()
 });
-var searchWorksOutput = z8.object({
-  title: z8.string().describe("The words asked for."),
-  words_searched: z8.array(z8.string()),
-  works: z8.array(workRowSchema),
-  page: z8.number().int(),
-  has_more: z8.boolean(),
+var searchWorksOutput = z9.object({
+  title: z9.string().describe("The words asked for."),
+  words_searched: z9.array(z9.string()).describe(
+    "The terms the index required, each of which has to appear in the title. A word is cut at an apostrophe and at a hyphen before the index sees it, so a word given as one can appear here as two, and a record carrying the pieces apart is a match."
+  ),
+  works: z9.array(workRowSchema),
+  page: z9.number().int(),
+  has_more: z9.boolean().describe(
+    "Whether the endpoint held at least one further row beyond this page, within the window the search read off the index. Read it alongside 'index_window_full': false on a full window says where the reading stopped rather than that the catalogue holds nothing else."
+  ),
+  index_window_full: z9.boolean().nullable().describe(
+    "Whether the fixed window this search reads off the index came back full. The window is read before the works are separated from the rest of the index, so a short list can rest on a full window. True means titles carrying these words sit past what was read, and another reading can bring back other rows. False means the window held everything that matched. Null when the endpoint stated no occupancy."
+  ),
   retrieved_at: retrievedAtSchema,
-  notes: z8.array(z8.string())
+  notes: z9.array(z9.string())
 });
-function emptyPageNote2(emptiness, page2, words) {
+function emptyPageNote3(emptiness, page2, words, windowFull) {
   const quoted = words.map((word) => `"${word}"`).join(", ");
+  if (windowFull) {
+    return `The window this search reads off the index came back full, and no work record survived the reading: every row of it named something the catalogue types as another kind of record. Whether a work carries ${quoted} in its title is unanswered here rather than answered no. Add a word to the title so that the window reaches further into the index.`;
+  }
   if (emptiness === "past_the_end") {
     return `Page ${page2} holds no row because it sits past the last row of this search. Works do carry ${quoted} in their title, and they are on earlier pages: call again with page=1, or with a lower page number, to read them.`;
   }
@@ -2103,7 +2598,10 @@ function emptyPageNote2(emptiness, page2, words) {
   }
   return `No work in the BnF catalogue has a title carrying every one of these words: ${quoted}. Every word given has to appear, so dropping one widens the search.`;
 }
-function emptyPageBody2(emptiness, page2, title) {
+function emptyPageBody3(emptiness, page2, title, windowFull) {
+  if (windowFull) {
+    return `No work record survived the reading for "${title}", out of a window of the index that came back full. Add a word to the title.`;
+  }
   if (emptiness === "past_the_end") {
     return `Page ${page2} of the search for "${title}" holds no row: it sits past the last row. Call again with page=1.`;
   }
@@ -2114,7 +2612,8 @@ function emptyPageBody2(emptiness, page2, title) {
 }
 async function runSearchWorks(client, args) {
   try {
-    const words = client.words(args.title);
+    const reading = client.searchReading(args.title);
+    const words = reading.words;
     if (words.length === 0) {
       return toToolError(
         invalidInput(
@@ -2133,8 +2632,21 @@ async function runSearchWorks(client, args) {
       );
     }
     const { data, cached, retrievedAt } = await client.searchWorks(args.title, args.limit, offset);
+    const terms = reading.terms;
+    const windowFull = data.indexWindowFull ?? null;
     const notes = [];
     if (cached) notes.push("Served from this server's short-lived in-memory cache.");
+    if (windowFull) {
+      notes.push(WINDOW_FULL_CAVEAT);
+      if (!data.hasMore) notes.push(WINDOW_FULL_AND_NO_MORE);
+    }
+    const split = words.filter((word) => /['-]/u.test(word));
+    if (split.length > 0) {
+      notes.push(
+        `${split.map((word) => `"${word}"`).join(", ")} reached the index as separate terms: it cuts a word at an apostrophe and at a hyphen, and requires each piece to appear in the title rather than in that arrangement, so a record writing the pieces apart is a match.`
+      );
+    }
+    notes.push(...readingNotes(reading, "title"));
     const works = data.rows.map((row) => ({
       id: row.id,
       title: row.title,
@@ -2145,9 +2657,9 @@ async function runSearchWorks(client, args) {
     }));
     if (works.length > 0) notes.push(NO_RANKING);
     if (works.some((work) => work.status === "provisional")) notes.push(PROVISIONAL_CAVEAT);
-    if (words.length > 2) {
+    if (terms.length > 2) {
       notes.push(
-        `All ${words.length} words were required: ${words.map((word) => `"${word}"`).join(", ")}. A record catalogued under a shorter form of the title carries fewer of them and falls out of the answer, so dropping a word widens the search.`
+        `All ${terms.length} terms were required: ${terms.map((term) => `"${term}"`).join(", ")}. A record catalogued under a shorter form of the title carries fewer of them and falls out of the answer, so dropping a word widens the search.`
       );
     }
     if (works.length > 0 && works.every((work) => work.status === "provisional")) {
@@ -2162,13 +2674,13 @@ async function runSearchWorks(client, args) {
     }
     let emptiness = "absent";
     if (works.length === 0) {
-      emptiness = await classifyEmptyPage(args.page, async () => {
+      emptiness = windowFull ? "absent" : await classifyEmptyPage(args.page, async () => {
         const first = await client.searchWorks(args.title, 1, 0);
         return first.data.rows.length > 0;
       });
-      notes.push(emptyPageNote2(emptiness, args.page, words));
+      notes.push(emptyPageNote3(emptiness, args.page, terms, windowFull === true));
     }
-    const body = works.length === 0 ? emptyPageBody2(emptiness, args.page, args.title) : `${works.length} work(s) whose title carries ${words.map((word) => `"${word}"`).join(" and ")}:
+    const body = works.length === 0 ? emptyPageBody3(emptiness, args.page, args.title, windowFull === true) : `${works.length} work(s) whose title carries ${terms.map((term) => `"${term}"`).join(" and ")}:
 ${works.map((work, index) => {
       const by = work.creators.length > 0 ? ` \xB7 ${work.creators.map((creator) => creator.name ?? creator.id).join(", ")}` : "";
       const when = work.date ? ` (${work.date})` : "";
@@ -2179,10 +2691,11 @@ ${works.map((work, index) => {
     return ok(
       {
         title: args.title,
-        words_searched: words,
+        words_searched: terms,
         works,
         page: args.page,
         has_more: data.hasMore,
+        index_window_full: windowFull,
         retrieved_at: retrievedAt,
         notes
       },
@@ -2203,9 +2716,10 @@ var READ_ONLY = {
 };
 var INSTRUCTIONS = [
   "Tools for data.bnf.fr, the open catalogue of the Biblioth\xE8que nationale de France. No API key and no account are needed.",
-  "The usual path is search_authors or search_works to get an identifier, then get_author, get_work or list_editions to read the record it names.",
+  "The usual path is search_authors or search_works to get an identifier, then get_author, get_work or list_editions to read the record it names. What a person wrote is list_works, which walks from a person to the works the catalogue names them the creator of; a title search cannot answer that, because it reads titles and a person's name in a title belongs to the books written about them.",
+  "A list of a person's works is one link the catalogue holds and not a bibliography: the catalogue credits a person on a record in other ways, and the BnF holds editions whose work it has never established as a record of its own, so a work missing from the list is not a work the person did not write. The catalogue states a work's form as a code from a vocabulary it publishes no label for, and it states no form at all on many works, so keeping the rows carrying one code finds the works that declare it and never all the works of that form.",
   "The BnF publishes these metadata on one condition: name the source and state the date they were retrieved. Every answer carries 'retrieved_at' for that reason, and repeating both alongside what you show is what the licence asks for.",
-  "Both searches read a full-text index that answers whether a title or a name matches and never scores how well, so rows come back in index order. Never present the first row as the best answer, and never describe a count as a ranking.",
+  "Both searches read a full-text index that answers whether a title or a name matches and never scores how well, so rows come back ordered by the address of the record. Never present the first row as the best answer, and never describe a count as a ranking. Every listing here is paged along that same order, so a page and the page after it hold different records and nothing between them is skipped.",
   "One person can hold several authority records, and search_authors returns all of them: show the caller the choice rather than picking one.",
   "A work record is either established, with an ARK of its own, or provisional, addressed under 'temp-work' while a cataloguer settles it. A provisional identifier can change, so prefer an established one when citing.",
   "The catalogue describes what the BnF holds; it does not hold the texts. A record can point at a digitised copy on Gallica, and those links are returned as addresses for a person to open. This server never requests gallica.bnf.fr, because the BnF places its metadata and its digitised contents under two different regimes, so it can say a document exists at a link and nothing about what is there.",
@@ -2279,6 +2793,17 @@ function createServer(options = {}) {
     },
     async (args) => runListEditions(client, args)
   );
+  server.registerTool(
+    "list_works",
+    {
+      title: "List the works a person is credited with",
+      description: listWorksDescription,
+      inputSchema: listWorksInput,
+      outputSchema: listWorksOutput,
+      annotations: READ_ONLY
+    },
+    async (args) => runListWorks(client, args)
+  );
   server.registerTool(
     "find_digitised",
     {