@capacms/mcp 0.2.0

package/lib/graphql-tools.mjs

@@ -0,0 +1,1177 @@
+/**
+ * graphql-tools.mjs — the tools that let an agent find, write, run and read
+ * queries against Capa's `/api/` read surface.
+ *
+ * The path an agent takes, and the tool for each step:
+ *
+ *   what is here?            capa_graphql_schema  (the map, one model, or SDL)
+ *   what does it look like?  capa_explore_data    (real values, measured)
+ *   write me a query         capa_graphql_build   (GraphQL + REST + SDK, checked)
+ *   run this query           capa_graphql_query
+ *   what went wrong?         capa_explain_error   (offline)
+ *
+ * The first three and capa_graphql_query are G plan 4.2's tools. The brief
+ * adds "explore data", which capa_explore_data does, and capa_explain_error
+ * answers the brief's "errors name the next tool" for errors an agent reads
+ * in a log rather than gets from a call.
+ *
+ * Every description says when to use the tool instead of its neighbours, every
+ * input schema refuses unknown keys (server.mjs checks arguments against it),
+ * every answer is bounded (lib/bound.mjs) and says what it cut, and every
+ * refusal names the next tool to call. The budgets are asserted in the tests.
+ *
+ * SCOPE. Every tool but capa_explain_error reads through `/api/graphql`, which
+ * serves any key holding `instance:read` for at least one model, so these
+ * tools use `scopePrefix` (a per-model `instance:read:<id>` counts). The
+ * schema they see is the key's own: a one-model key sees one model, and no
+ * output here names a model the key cannot read.
+ */
+import { reads } from "./annotations.mjs";
+import { answerSchema, BOUNDED, DRAFTS_NOTE, MAX_CHARS, READ_WITH_KEYS, readWith } from "./answers.mjs";
+import { apiNextGet, apiNextPost, CapaApiError, DEFAULT_API_VERSION } from "./client.mjs";
+import { boundAnswer, DEFAULT_MAX_CHARS, someNames } from "./bound.mjs";
+import { BuildError, didYouMean, displayName, entriesPerEntry, findModel, firstWithin, isHop, planQuery, printGraphQL, printRest, RestOnlyModel } from "./graphql/build.mjs";
+import { connectionsOf, withAfter } from "./graphql/document.mjs";
+import { listedWithin, relationsWithMore } from "./graphql/more.mjs";
+import { loadSchema, namedType } from "./graphql/schema.mjs";
+import { whenNotServed } from "./graphql/served.mjs";
+import { splitOutside } from "./graphql/names.mjs";
+import { printSDL } from "./graphql/sdl.mjs";
+import { modelSDLUri } from "./resources.mjs";
+import { budgetOf, explainOne, hintedFix, nextSteps, nextTool, normalizeErrors } from "./error-guide.mjs";
+import { COUNTS_LEGEND, exploreQuery, fieldStats, hiddenValueRequests, listRequests, measurableFields, nullListRequests, pageSizeFor, samples, statusCounts, storedRequest } from "./explore.mjs";
+
+/** Every tool here but capa_explain_error reads through /api/graphql, which a deployment can switch off (registry.mjs). */
+const SCOPE = { surface: "api", scopePrefix: "instance:read", feature: "graphql" };
+/** What a cut schema answer tells the agent: one model at a time is always small. */
+const SCHEMA_HINT = "Pass model for one model at a time.";
+/** What a cut answer about one model tells the agent: it asked for one model already, and that model's SDL is a resource. */
+const modelHint = (model) => `This model has more than one answer holds: read the resource ${modelSDLUri(model.namespace)} for its whole SDL.`;
+/** What a schema map too big even to name every model tells the agent. */
+const NAMES_HINT = "Pass model with any model's namespace, name or type: an unknown one comes back with the nearest.";
+/** What a cut built query tells the agent. */
+const BUILD_HINT = "Ask for fewer fields or a smaller first, or raise maxChars.";
+/** How to read the rest of a clipped value: capa_graphql_query's slice, on the same document. */
+const readOnWithSlice = (clip) =>
+  `Call capa_graphql_query again with the same query and slice: { path: "${clip.path}", offset: ${clip.kept} } for the rest.`;
+/** The same from capa_graphql_build's run, whose data sits under result. */
+const readOnFromBuild = (clip) => {
+  const path = clip.path.replace(/^result\./, "");
+  return `Run this query with capa_graphql_query and slice: { path: "${path}", offset: ${clip.kept} } for the rest.`;
+};
+const BUILD_FALLBACK_HINT =
+  "Raise maxChars, or run the query with capa_graphql_query, whose answer does not repeat the document.";
+/**
+ * The parts of a built query's answer that are never cut: the document and its
+ * REST twin are the point of the tool, and what the key read decides what the
+ * result means. Only parts that overrun maxChars on their own are left out,
+ * whole (lib/bound.mjs).
+ */
+const BUILT_PARTS = ["query", "variables", "operationName", "rest", "restFromApi", "environment", "drafts", "notFound"];
+/**
+ * The parts of a query's answer that give way, whole and in this order,
+ * before its data is cut past one entry per list: the drafts note, since
+ * `environment` still says which key read it, then the REST twin, which a
+ * `nodes(ids:)` read's every id can make longer than the budget. The cost
+ * describes the data, so it stays beside it.
+ */
+const QUERY_SPARE = ["drafts", "rest"];
+/** What a cut explanation tells the agent. */
+const EXPLAIN_HINT = "Pass the error object, or just its code, rather than the whole log.";
+/** What a cut measurement tells the agent: this tool takes field and sample, not fields or first. */
+const EXPLORE_HINT = "Pass field to measure one field, or sample: 0.";
+/**
+ * The parts of a measurement left out whole before any field's numbers are
+ * cut, in order: the sample entries, then the legend of what each count means
+ * (the output schema's `counts` says where to find it).
+ */
+const EXPLORE_EXTRAS = ["samples", "counts"];
+const SYSTEM_NOTE =
+  "Every model type also has id, model, status, createdAt, updatedAt, publishedAt, _version, _tags, _folder. " +
+  "Filters and sorts take id, createdAt, updatedAt and publishedAt of those.";
+/** The system fields every sort takes (N8), which every filter takes too. */
+const SORTED_SYSTEM = new Set(["id", "createdAt", "updatedAt", "publishedAt"]);
+
+/** SYSTEM_NOTE, and the system fields `models`' filters take beyond the sorted four, as the schema declares them (`_tags`, amendment 56). */
+function systemNote(models) {
+  const more = [...new Set(models.flatMap((m) => m.systemFilters.map((f) => f.name)))].filter((name) => !SORTED_SYSTEM.has(name));
+  if (!more.length) return SYSTEM_NOTE;
+  const names = more.length === 1 ? more[0] : `${more.slice(0, -1).join(", ")} and ${more.at(-1)}`;
+  return `${SYSTEM_NOTE} Filters also take ${names}.`;
+}
+
+// ------------------------------------------------------------ small helpers ---
+
+/**
+ * A `BuildError` as an in-band answer: the agent corrects itself from it. A
+ * wrong name carries the nearest names, every name, and the tool that lists
+ * them; a structural refusal states its fix in `error` itself.
+ */
+function buildRefusal(error) {
+  // A model GraphQL leaves out is no misspelling: REST reads it, and capa_read_entries is registered for it.
+  if (error instanceof RestOnlyModel) return { error: error.message, next: "capa_read_entries" };
+  const out = { error: error.message };
+  if (error.didYouMean.length) out.didYouMean = error.didYouMean;
+  if (error.available.length) Object.assign(out, { available: error.available, next: "capa_graphql_schema" });
+  return out;
+}
+
+/** One field as a line of the map: `title: String`, `author -> authors`, `coauthors ->> authors`, marked when deprecated. */
+function fieldLine(field) {
+  const line =
+    field.kind === "relation"
+      ? `${field.name} -> ${field.target}`
+      : field.kind === "relationList"
+        ? `${field.name} ->> ${field.target}`
+        : `${field.name}: ${field.graphqlType}`;
+  return field.deprecationReason ? `${line} (deprecated)` : line;
+}
+
+/** The API's GraphQL errors, trimmed to what an agent acts on. */
+function trimErrors(errors) {
+  return (errors ?? []).map((e) => {
+    const out = { message: e.message };
+    if (e.extensions?.code) out.code = e.extensions.code;
+    if (e.extensions?.hint) out.hint = e.extensions.hint;
+    if (e.path) out.path = e.path;
+    return out;
+  });
+}
+
+/** `{ next }` naming the tool that helps with these errors, or nothing when none does. */
+function nextField(errors) {
+  const tool = nextTool(errors);
+  return tool ? { next: tool } : {};
+}
+
+/**
+ * For a built list the API refused over the entries budget, the changes that
+ * fit: the refusal states the limit, and the plan what one entry can read
+ * (REST's pre-SQL bound), so the answer is a number, not "ask for less". The
+ * API's hint often names a relation list's first instead of the root's; both
+ * fit, so both are named, the API's first, each with its numbers as written.
+ */
+function fittingFirst(plan, errors) {
+  if (plan.mode !== "list") return {};
+  const root = plan.model.listField;
+  const refusal = errors.find((e) => {
+    const budget = budgetOf(e.message);
+    return budget?.measure === "entries" && budget.root === root;
+  });
+  if (!refusal) return {};
+  const budget = budgetOf(refusal.message);
+  const limit = budget.written.limit;
+  const hinted = hintedFix(refusal.hint);
+  const apiChange = hinted?.field && hinted.field !== root ? `${hinted.field}(${hinted.argument}: ${hinted.value})` : null;
+  const first = firstWithin(plan, budget.limit);
+  if (first === null) return apiChange ? { fix: `${apiChange} fits the limit of ${limit}, as the API's hint says.` } : {};
+  const perEntry = entriesPerEntry(plan.fields);
+  if (first < 1) {
+    const lower = `One ${plan.model.typeName} entry can read ${perEntry} with its relations, over the limit of ${limit}`;
+    return { fix: apiChange ? `${lower}: pass ${apiChange}, as the API's hint says.` : `${lower}: lower first on its relation lists.` };
+  }
+  const each = `each ${plan.model.typeName} entry can read ${perEntry} with its relations`;
+  return {
+    fix: apiChange
+      ? `Either change fits the limit of ${limit}: ${apiChange}, as the API's hint says, or first: ${first} on ${root}, since ${each}.`
+      : `E${each.slice(1)}, so first: ${first} fits the limit of ${limit}.`,
+  };
+}
+
+/**
+ * The API refused the whole request: a status other than 200, with its
+ * errors, and for each code the fix and the tool that helps (error-guide.mjs).
+ */
+class QueryRefused extends Error {
+  constructor(status, errors) {
+    const lines = errors.slice(0, 5).map((e) => `- ${e.code ? `${e.code}: ` : ""}${e.message}${e.hint ? ` Hint: ${e.hint}` : ""}`);
+    super(`Capa refused the query (HTTP ${status}).\n${lines.join("\n")}\n${nextSteps(errors)}`);
+    this.status = status;
+    this.errors = errors;
+  }
+}
+
+/**
+ * POST a document and answer the API's body. It asks for `extensions.capa`,
+ * which the API sends only to a development key unless asked (spec 17,
+ * amendment 119): the detailed cost, the REST twin and the key's environment
+ * are part of every answer these tools give. A refused request throws
+ * `QueryRefused`, whose message lists every error with its hint and the next
+ * step, which the server turns into an `isError` result.
+ */
+async function postQuery(config, query, variables, operationName) {
+  try {
+    return await apiNextPost(config, "/api/graphql", { query, variables, operationName, extensions: { capa: true } });
+  } catch (error) {
+    if (!(error instanceof CapaApiError)) throw error;
+    const notServed = whenNotServed(config, error);
+    if (notServed !== error) throw notServed;
+    let parsed = null;
+    try {
+      parsed = JSON.parse(error.body);
+    } catch {
+      parsed = null;
+    }
+    const errors = trimErrors(parsed?.errors ?? (parsed?.error ? [{ message: parsed.error.message, extensions: parsed.error }] : []));
+    throw new QueryRefused(error.status, errors.length ? errors : [{ message: error.message }]);
+  }
+}
+
+/**
+ * Run a document: a 200 answers `{ data, errors?, cost, budget, deprecations?, rest }`, and `environment`, the
+ * key's, which `readWith` reads. `budget` is `extensions.cost.budget`, `{ counted, limit }`: what the API
+ * counted against the 5,000-entry limit before it read (spec 17, amendment 138), so an agent sees how near a
+ * document is to a refusal. `deprecations` is each deprecated member the document used, `{ coordinate, reason }`
+ * (amendment 136), only when there is one.
+ */
+async function runQuery(config, query, variables, operationName) {
+  const body = await postQuery(config, query, variables, operationName);
+  const out = { data: body.data ?? null };
+  const errors = trimErrors(body.errors);
+  if (errors.length) out.errors = errors;
+  if (body.extensions?.capa?.cost) out.cost = body.extensions.capa.cost;
+  if (body.extensions?.cost?.budget) out.budget = body.extensions.cost.budget;
+  if (body.extensions?.deprecations?.length) out.deprecations = body.extensions.deprecations;
+  if (body.extensions?.capa?.rest) out.rest = body.extensions.capa.rest;
+  if (body.extensions?.capa?.environment) out.environment = body.extensions.capa.environment;
+  return out;
+}
+
+
+// Split so the env-template scanner does not count text this tool writes for
+// the user's code as a variable this package reads (as apps/admin dev-query.ts).
+const ENV = "process" + ".env";
+
+/**
+ * What the SDK code says for a legacy key: `pk_`, `sk_` or unprefixed, every
+ * key but `cap_`, which `@capacms/sdk/next` reads with and warns about once.
+ */
+const LEGACY_KEY_NOTE =
+  "@capacms/sdk/next reads with this legacy key and warns once. Draft previews need a cap_ key: mint one in the Capa admin under Developers > Keys.";
+
+const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * The code for a built query in the user's app, typed the way the SDK's own
+ * README types it:
+ *
+ * - `document`: the query as a `#graphql` literal, which `capa-codegen
+ *   --graphql` reads, so `data` and the variables are typed from its text.
+ * - `next`: a Next.js server component's read, through `graphql()` from
+ *   `@capacms/sdk/nextjs`: drafts and edit marks under preview, the Next
+ *   cache tagged with every model the query reads (so `revalidateFromWebhook`
+ *   refreshes the page on a publish), and never a cached error: graphql()
+ *   keeps a read in Next's data cache itself, with no `unstable_cache` passed.
+ *   The models are `<Name>Models`, which `capa-codegen --graphql` writes
+ *   beside the document's types, so the tags follow the query when it is
+ *   edited, rather than a list written once here that would go stale.
+ * - `node`: anywhere else, with `createClient` from `@capacms/sdk/next`.
+ * - `rest`: the REST twin, with the same `capa`.
+ *
+ * The SDK's consumer type test compiles each of them, as handed over
+ * (packages/sdk/test/types/mcp-snippets.ts). CAPA_API_URL and CAPA_KEY are
+ * the names /nextjs reads. `@capacms/sdk/next` reads with any key, and a
+ * legacy key's code notes the `cap_` key draft previews need.
+ */
+export function sdkSnippets(config, summary, plan, built, rest) {
+  const version = summary.version || DEFAULT_API_VERSION;
+  const note = config.family === "cap" ? {} : { note: LEGACY_KEY_NOTE };
+  const name = built.operationName;
+  const document =
+    "// Run capa-codegen --graphql after saving this: it types data and the variables from this text.\n" +
+    `const ${name} = \`#graphql\n${built.query}\n\`;`;
+  const vars = JSON.stringify(built.variables);
+  const next =
+    'import { draftMode, headers } from "next/headers";\n' +
+    'import { graphql, tagsFor } from "@capacms/sdk/nextjs";\n' +
+    `import { ${name}Models } from "./capa-graphql"; // written by capa-codegen --graphql\n` +
+    "// In a server component:\n" +
+    `const { data, errors } = await graphql(${name}, ${vars}, {\n` +
+    "  draftMode,\n" +
+    "  headers,\n" +
+    `  tags: tagsFor({ namespace: ${name}Models }),\n` +
+    "  revalidate: 60,\n" +
+    "});";
+  const node =
+    'import { createClient } from "@capacms/sdk/next";\n' +
+    `const capa = createClient({ baseUrl: ${ENV}.CAPA_API_URL!, apiKey: ${ENV}.CAPA_KEY!, version: "${version}" });\n` +
+    `const { data, errors } = await capa.graphql(${name}${Object.keys(built.variables).length ? `, ${vars}` : ""});`;
+  const namespace = JSON.stringify(plan.model.namespace);
+  if (plan.mode === "single") {
+    return { ...note, document, next, node, rest: `const entry = await capa.entries.get(${namespace}, ${JSON.stringify(plan.id)}, { select: ${JSON.stringify(rest.select)} });` };
+  }
+  const options = [`select: ${JSON.stringify(rest.select)}`];
+  const param = (key) => rest.params.find(([k]) => k === key)?.[1];
+  if (param("where")) options.push(`where: ${param("where")}`);
+  // A quoted namespace may hold a comma (`"a,b"`), so the keys are split outside quotes.
+  if (param("sort")) options.push(`sort: ${JSON.stringify(splitOutside(param("sort"), ",", { nested: false }))}`);
+  if (param("limit")) options.push(`limit: ${param("limit")}`);
+  if (param("count")) options.push("count: true");
+  if (param("after")) options.push(`after: ${JSON.stringify(param("after"))}`);
+  if (param("before")) options.push(`before: ${JSON.stringify(param("before"))}`);
+  return { ...note, document, next, node, rest: `const page = await capa.entries.list(${namespace}, { ${options.join(", ")} });` };
+}
+
+/**
+ * The parts of `sdkSnippets` each `code` choice hands over. `document` goes
+ * with the code that runs it, which names it; the REST read stands alone.
+ */
+const CODE_PARTS = {
+  next: ["document", "next"],
+  node: ["document", "node"],
+  rest: ["rest"],
+  all: ["document", "next", "node", "rest"],
+};
+
+/** The SDK code `code` asks for, with a legacy key's note, or null for `none`. */
+function sdkCode(code, snippets) {
+  const parts = CODE_PARTS[code];
+  if (!parts) return null;
+  const { note, ...all } = snippets;
+  return { ...(note ? { note } : {}), ...Object.fromEntries(parts.map((part) => [part, all[part]])) };
+}
+
+/** A scope that names one model by id: `instance:read:<uuid>`. */
+const MODEL_SCOPE = /^(.+):([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+
+/**
+ * The key's scopes as an agent can use them: a scope on one model names the
+ * model by namespace (`instance:read:articles`), from the models `/api/me`
+ * lists with their ids, since a raw id is nothing a query or a tool takes. A
+ * scope on a model the key reads nothing of is not in that list; it is counted
+ * rather than printed as an id.
+ */
+export function readableScopes(scopes, models) {
+  const namespaces = new Map((Array.isArray(models) ? models : []).map((m) => [m.id, m.namespace]));
+  const named = [];
+  let unnamed = 0;
+  for (const scope of scopes) {
+    const match = MODEL_SCOPE.exec(scope);
+    if (!match) named.push(scope);
+    else if (namespaces.has(match[2])) named.push(`${match[1]}:${namespaces.get(match[2])}`);
+    else unnamed++;
+  }
+  const shown = named.length > 12 ? [...named.slice(0, 12), `+${named.length - 12} more`] : named;
+  return unnamed ? [...shown, `+${unnamed} on models this key reads no entries of`] : shown;
+}
+
+async function keySummary(config) {
+  try {
+    const { data } = await apiNextGet(config, "/api/me");
+    const key = { environment: data?.environment, bundle: data?.bundle };
+    if (Array.isArray(data?.scopes)) key.scopes = readableScopes(data.scopes, data.models);
+    if (key.environment === "development") key.drafts = DRAFTS_NOTE;
+    return key;
+  } catch (error) {
+    return { unavailable: error instanceof CapaApiError ? `${error.status}${error.code ? ` ${error.code}` : ""}` : "unreachable" };
+  }
+}
+
+/**
+ * Every model this key can read, one line per field. Over the budget, each
+ * model's field list is shortened and every model stays named, since a model
+ * the map leaves out is one the agent cannot know to ask for. Only when the
+ * names alone do not fit are models cut.
+ */
+async function schemaMap(config, summary) {
+  const map = {
+    version: summary.version,
+    key: await keySummary(config),
+    models: [
+      ...summary.models.map((m) => ({
+        model: m.namespace,
+        name: displayName(m),
+        type: m.typeName,
+        graphql: `${m.listField}, ${m.singleField}(id)`,
+        rest: `/api/entries/${m.namespace}`,
+        fields: m.fields.map(fieldLine),
+      })),
+      // Listed, since a model the map leaves out is one the agent cannot know to ask for; REST reads them.
+      ...(summary.restOnly ?? []).map((namespace) => ({
+        model: namespace,
+        graphql: "none: readable over REST only; capa_read_entries reads it",
+        rest: `/api/entries/${namespace}`,
+      })),
+    ],
+    system: systemNote(summary.models),
+    next: "Pass model for filters, sorts and an example, or call capa_graphql_build.",
+  };
+  const bounded = boundAnswer(map, DEFAULT_MAX_CHARS, { hint: SCHEMA_HINT, whole: ["models"] });
+  if (!bounded.note) return bounded;
+  const names = {
+    ...map,
+    models: map.models.map(({ model, name, type, graphql, rest }) => (type ? { model, name, type } : { model, graphql, rest })),
+    note: `${map.models.length} models are too many to list with their fields in one answer. Pass model for one model's fields, filters and sorts.`,
+  };
+  return boundAnswer(names, DEFAULT_MAX_CHARS, { hint: NAMES_HINT });
+}
+
+/**
+ * What a media value holds, read from the schema's `Media` type: its fields in
+ * order, what `type` means, and the kinds of file it takes when its type is
+ * an enum (MediaKind, spec 17 amendment 114). Only for a model with a media
+ * field.
+ */
+function mediaNote(introspection, model) {
+  if (!model.fields.some((f) => f.kind === "media")) return {};
+  const types = introspection.__schema.types;
+  const media = types.find((t) => t.name === "Media");
+  if (!media?.fields) return {};
+  const type = media.fields.find((f) => f.name === "type");
+  let named = type?.type;
+  while (named?.ofType) named = named.ofType;
+  const kinds = named?.kind === "ENUM" ? types.find((t) => t.name === named.name)?.enumValues?.map((v) => v.name) : null;
+  const meaning = type?.description ? ` type: ${type.description}` : "";
+  const values = kinds?.length ? ` ${named.name}: ${kinds.join(", ")}.` : "";
+  return { media: `Media fields: ${media.fields.map((f) => f.name).join(", ")}.${meaning}${values}` };
+}
+
+/** `{ name: reason }` for each deprecated one of `values` (arguments or input fields), or null when none is. */
+function deprecatedOf(values) {
+  const out = Object.fromEntries((values ?? []).filter((v) => v.isDeprecated).map((v) => [v.name, v.deprecationReason ?? "No longer supported"]));
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * What a later Capa-Version phases out of reading `model`, with each reason:
+ * the arguments of its root fields, as `articles(before:)`, and per filter
+ * field the operators its filter input deprecates. Each still works until
+ * then, so the builders take them.
+ */
+function inputDeprecations(introspection, model) {
+  const types = new Map(introspection.__schema.types.map((t) => [t.name, t]));
+  const roots = types.get(introspection.__schema.queryType.name)?.fields ?? [];
+  const args = {};
+  for (const root of roots.filter((r) => r.name === model.listField || r.name === model.singleField)) {
+    for (const [name, reason] of Object.entries(deprecatedOf(root.args) ?? {})) args[`${root.name}(${name}:)`] = reason;
+  }
+  const filters = new Map((types.get(model.filterType)?.inputFields ?? []).map((input) => [input.name, input]));
+  const operators = (fieldName) => {
+    const input = filters.get(fieldName);
+    return input ? deprecatedOf(types.get(namedType(input.type))?.inputFields) : null;
+  };
+  return { args: Object.keys(args).length ? args : null, operators };
+}
+
+/** One model: every field's type, filter operators and sortability, the sort values, an example. */
+function modelDetail(summary, model, introspection) {
+  const plan = planQuery(summary, { model: model.namespace, first: 5 });
+  const example = printGraphQL(plan);
+  const deprecations = inputDeprecations(introspection, model);
+  const graphql = { list: model.listField, single: model.singleField, filter: model.filterType, sort: model.sortType };
+  if (deprecations.args) graphql.deprecatedArgs = deprecations.args;
+  return {
+    model: model.namespace,
+    type: model.typeName,
+    name: displayName(model),
+    graphql,
+    rest: `/api/entries/${model.namespace}`,
+    fields: model.fields.map((f) => {
+      const out = { name: f.name, type: f.graphqlType, capa: f.arrayType ? `${f.capaType} of ${f.arrayType}` : f.capaType };
+      if (f.namespace !== f.name) out.namespace = f.namespace;
+      if (f.target) out.target = f.target;
+      // Operators take a value; hops are fields of the related model, each taking operators of its own.
+      const operators = f.filterOps.filter((op) => !isHop(f, op));
+      const hops = f.filterOps.filter((op) => isHop(f, op));
+      if (operators.length) out.filter = operators;
+      const deprecatedFilter = deprecations.operators(f.name);
+      if (deprecatedFilter) out.deprecatedFilter = deprecatedFilter;
+      if (hops.length) out.hops = hops;
+      if (f.sortable) out.sortable = true;
+      if (f.deprecationReason) out.deprecated = f.deprecationReason;
+      return out;
+    }),
+    sort: model.sortValues,
+    example: { query: example.query, variables: example.variables, rest: printRest(summary, plan).url },
+    system: systemNote([model]),
+    ...mediaNote(introspection, model),
+  };
+}
+
+/**
+ * One model's details with its SDL (compact, sdl.mjs), each whole: an SDL cut
+ * mid-type is text nobody can parse, and a field list cut to one field says
+ * nothing. When both do not fit, the SDL is left out and the note says where
+ * to read it.
+ */
+export function detailWithSDL(detail, introspection, summary, model, maxChars = DEFAULT_MAX_CHARS) {
+  const { sdl, alsoReferenced } = printSDL(introspection, summary, [model.namespace], { compact: true });
+  const both = { ...detail, sdl, ...(alsoReferenced.length ? { alsoReferenced } : {}) };
+  if (JSON.stringify(both).length <= maxChars) return both;
+  const note =
+    `sdl is left out: ${model.namespace}'s SDL is ${sdl.length.toLocaleString("en-US")} characters, more than fits beside its details in ` +
+    `${maxChars.toLocaleString("en-US")}. Read it from the resource ${modelSDLUri(model.namespace)}.`;
+  const left = { path: "sdl", kept: 0, total: 1 };
+  const bounded = boundAnswer(detail, maxChars - JSON.stringify({ note, truncated: [left] }).length, { hint: modelHint(model) });
+  return { ...bounded, note: bounded.note ? `${bounded.note} ${note}` : note, truncated: [...(bounded.truncated ?? []), left] };
+}
+
+/**
+ * The whole schema's SDL (compact, sdl.mjs), cut between models so the
+ * answer, serialized and with its note, is at most `maxChars`. A cut keeps
+ * Query and the shared types first, then whole models in namespace order,
+ * each with every type it uses, and names the models it left out.
+ */
+export function wholeSDL(introspection, summary, maxChars = DEFAULT_MAX_CHARS) {
+  const { sdl } = printSDL(introspection, summary, undefined, { compact: true });
+  const whole = { version: summary.version, sdl };
+  if (JSON.stringify(whole).length <= maxChars) return whole;
+  const all = summary.models.map((m) => m.namespace);
+  // Below one whole model nothing is worth printing: Query and the shared types only matter beside one.
+  const firstModels = (count) => ({
+    version: summary.version,
+    sdl: count ? printSDL(introspection, summary, all.slice(0, count), { compact: true }).sdl : "",
+    truncated: `Printed ${count} of ${all.length} models, each with the types it uses. Not printed: ${someNames(all.slice(count))}. Pass model for one.`,
+  });
+  // The serialized size grows with the count, so the largest count that fits is found by bisection.
+  let fits = 0;
+  let over = all.length;
+  while (over - fits > 1) {
+    const mid = (fits + over) >> 1;
+    if (JSON.stringify(firstModels(mid)).length <= maxChars) fits = mid;
+    else over = mid;
+  }
+  return firstModels(fits);
+}
+
+/**
+ * Run a built query with each entry's cursor selected beside it (`edges {
+ * cursor }`) in the root list and in every relation list, and each relation
+ * list's pageInfo, so that when the answer is cut, a list's endCursor can be
+ * the cursor of the last entry kept, at any depth. The edges then leave the
+ * result; the relation lists' pageInfo leaves it once read (the document
+ * handed over selects neither). The cursors are keyed by where each list's
+ * connection sits in the answer (`result.data.bins.nodes[0].items`).
+ */
+async function runWithCursors(config, plan, built) {
+  const result = await runQuery(config, printGraphQL(plan, { cursors: true }).query, built.variables, built.operationName);
+  const cursors = {};
+  const collect = (value, path) => {
+    if (Array.isArray(value)) {
+      value.forEach((item, i) => collect(item, `${path}[${i}]`));
+      return;
+    }
+    if (!isPlainObject(value)) return;
+    if (Array.isArray(value.edges) && Array.isArray(value.nodes)) {
+      cursors[path] = value.edges.map((edge) => edge?.cursor);
+      delete value.edges;
+    }
+    for (const [key, inner] of Object.entries(value)) collect(inner, `${path}.${key}`);
+  };
+  collect(result.data, "result.data");
+  return { result, cursors };
+}
+
+/**
+ * One page's entries as the API stores them, by id: each one's `fields` from
+ * REST, relations as references (explore.mjs says why it is read twice).
+ */
+async function readStored(config, model, fields, nodes) {
+  const request = storedRequest(model, fields, nodes.map((node) => node.id));
+  if (!request) return [];
+  const { data } = await apiNextGet(config, request.path, request.query);
+  return (Array.isArray(data) ? data : []).map((entry) => [entry.id, entry.fields ?? {}]);
+}
+
+/**
+ * The entries each of `requests` matches, by field namespace, added to
+ * `found`: the values REST shows as null although one is stored
+ * (`hiddenValueRequests`), or the relation lists it shows empty that are
+ * stored as null (`nullListRequests`) or as a list (`listRequests`),
+ * explore.mjs.
+ */
+async function readMatches(config, requests, found) {
+  for (const request of requests) {
+    const { data } = await apiNextGet(config, request.path, request.query);
+    const ids = found.get(request.namespace) ?? new Set();
+    for (const entry of Array.isArray(data) ? data : []) ids.add(entry.id);
+    found.set(request.namespace, ids);
+  }
+}
+
+/**
+ * An answer bound to `maxChars` with the relation lists that hold more than
+ * they show named at its top (`more`, lib/graphql/more.mjs) and a `note`
+ * saying how to read on. The lists and the note are paid for first, so the
+ * whole still fits; a list's cursor is left out before the list is.
+ */
+function boundWithMore(bound, listsOf, uncut, maxChars, noteOf) {
+  const size = (value) => JSON.stringify(value).length;
+  // A quarter of the budget for the lists, or what the first one takes whole, up to half.
+  const share = (lists) => Math.min(Math.floor(maxChars / 2), Math.max(Math.floor(maxChars / 4), size(lists.slice(0, 1))));
+  const extra = (lists, budget) => {
+    const more = listedWithin(lists, budget);
+    return { more, note: noteOf(lists, more) };
+  };
+  /** `out` with the lists it holds named in the room left, or null when they do not fit. */
+  const withLists = (out, lists) => {
+    const room = maxChars - size(out) - 8;
+    const { more, note } = extra(lists, room - size(noteOf(lists, lists.slice(0, 1))) - 16);
+    const joined = { ...out, more, note: out.note ? `${out.note} ${note}` : note };
+    return size(joined) <= maxChars ? joined : null;
+  };
+  // The lists are read from the answer as cut: a cut list's endCursor is then
+  // the cursor of the last entry kept (lib/bound.mjs), so reading on skips none.
+  const first = listsOf(uncut);
+  let reserve = first.length ? size(extra(first, share(first))) + 8 : 0;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const out = bound(maxChars - reserve);
+    const lists = listsOf(out);
+    if (!lists.length) break;
+    const joined = withLists(out, lists);
+    if (joined) return joined;
+    reserve = size(extra(lists, share(lists))) + 8;
+  }
+  // The room kept for the lists cost the answer its data, or they never fit:
+  // the data comes first, and the lists go beside it only if they still fit.
+  const whole = bound(maxChars);
+  const lists = listsOf(whole);
+  return (lists.length && withLists(whole, lists)) || whole;
+}
+
+/** "1 relation list holds more entries than it shows", with how many are listed when not all. */
+function moreLead(lists, more) {
+  const maybe = lists.some((list) => list.pageInfo === false) ? ", or may hold," : "";
+  const lead = lists.length === 1 ? `1 relation list holds${maybe} more entries than it shows` : `${lists.length} relation lists hold${maybe} more entries than they show`;
+  return lists.length > more.length ? `${lead}; more names ${more.length}.` : `${lead}: see more.`;
+}
+
+/** capa_graphql_query's note: the lists with a next are read on by calling it; the others by hand. */
+function queryMoreNote(lists, more) {
+  const next = more.some((list) => list.next) ? " Call capa_graphql_query with a list's next to read on from its endCursor." : "";
+  const byHand = more.some((list) => !list.next && list.pageInfo !== false && list.endCursor !== undefined)
+    ? " A list under a list pages on only in a read of one entry: read the entry more[].entry with its single root field " +
+      "(article(id: ...) for articles), follow the path to the list, and pass its endCursor as after on it."
+    : "";
+  const blind = more.some((list) => list.pageInfo === false)
+    ? " A list with pageInfo: false selected no pageInfo, so it fills its page and may hold more: select pageInfo { hasNextPage endCursor } on it for its cursor."
+    : "";
+  const cut = more.some((list) => list.pageInfo !== false && list.endCursor === undefined)
+    ? " A list with no endCursor was cut to fit this answer: truncated says how to read on without skipping any."
+    : "";
+  return `${moreLead(lists, more)}${next}${byHand}${blind}${cut}`;
+}
+
+/**
+ * The capa_graphql_query arguments that read on the relation list `list`
+ * from its endCursor: the same document with that list's `after` set. Only
+ * for a list every entry above which is one entry (the path holds no list
+ * position), since the API pages a relation list only there; a list under a
+ * list is read on by hand, from `entry`.
+ */
+function queryNextRead(args, list) {
+  if (typeof list.endCursor !== "string" || /\[\d+\]/.test(list.path)) return null;
+  const read = withAfter(args.query, args.variables, args.operationName, list.path.replace(/^data\./, ""), list.endCursor);
+  if (!read) return null;
+  return {
+    query: read.query,
+    ...(read.variables && Object.keys(read.variables).length ? { variables: read.variables } : {}),
+    ...(args.operationName ? { operationName: args.operationName } : {}),
+  };
+}
+
+/** capa_graphql_build's note: the read that goes on is in each list's `next`. */
+function buildMoreNote(lists, more) {
+  return (
+    `${moreLead(lists, more)} Call capa_graphql_query with a list's next to read on: it reads the one entry that ` +
+    "holds the list from the list's endCursor, and names what is still left the same way."
+  );
+}
+
+/**
+ * The capa_graphql_query arguments that read on the relation list at `path`
+ * from its endCursor: the entry that holds it (`entry`, its id) read alone,
+ * the single relations between them, and the list as the plan selects it,
+ * with its pageInfo.
+ */
+function nextRead(plan, at, list) {
+  if (typeof list.entry !== "string" || typeof list.endCursor !== "string") return null;
+  const keys = list.path.replace(/\[\d+\]/g, "").slice(at.length + 1).split(".").slice(1);
+  let model = plan.model;
+  let entryModel = plan.model;
+  let planned = plan.fields;
+  let chain = [];
+  for (const key of keys) {
+    if (key === "nodes" || key === "edges" || key === "node") {
+      entryModel = model;
+      chain = [];
+      continue;
+    }
+    const field = planned.find((p) => p.name === key);
+    if (!field?.target) return null;
+    chain.push(field);
+    model = field.target;
+    planned = field.children;
+  }
+  if (!chain.length) return null;
+  let inner = { ...chain.pop(), after: list.endCursor };
+  while (chain.length) inner = { ...chain.pop(), children: [{ name: "id", field: null }, inner] };
+  const read = {
+    model: entryModel,
+    mode: "single",
+    id: list.entry,
+    fields: [{ name: "id", field: null }, inner],
+    totalCount: false,
+    operationName: `${entryModel.typeName}ById`,
+  };
+  return printGraphQL(read, { pages: true });
+}
+
+/**
+ * `data` without the relation lists' pageInfo, which the document handed over
+ * does not select. With `keepMore`, a pageInfo that says more comes stays: it
+ * is the only word of it when the answer had no room to name the list.
+ */
+function withoutNestedPages(data, plan, { keepMore = false } = {}) {
+  const strip = (value) => {
+    if (Array.isArray(value)) return value.forEach(strip);
+    if (!isPlainObject(value)) return;
+    for (const inner of Object.values(value)) {
+      if (isPlainObject(inner) && Array.isArray(inner.nodes)) {
+        if (!(keepMore && inner.pageInfo?.hasNextPage === true)) delete inner.pageInfo;
+        strip(inner.nodes);
+      } else {
+        strip(inner);
+      }
+    }
+  };
+  const root = data?.[plan.mode === "single" ? plan.model.singleField : plan.model.listField];
+  strip(plan.mode === "single" ? root : root?.nodes);
+}
+
+// -------------------------------------------------------------------- tools ---
+
+/** The steps of a `clipped` path: `data.scalars.nodes[3].body` is data, scalars, nodes, 3, body. */
+function pathSteps(path) {
+  return [...String(path).matchAll(/\[(\d+)\]|([^.[\]]+)/g)].map(([, index, key]) => (index !== undefined ? Number(index) : key));
+}
+
+/**
+ * capa_graphql_query with `slice`: one text value of the answer, from
+ * `offset`, as `text`, as much of it as `maxChars` holds. The value is found
+ * by the path a `clipped` note names, in the same run's answer. Where more
+ * follows, `clipped` says so as a cut answer does, its `kept` the offset to
+ * read on from, and the hint gives the next call.
+ */
+function sliceOf(answer, { path, offset = 0 }, maxChars) {
+  const value = pathSteps(path).reduce((node, step) => (node == null ? undefined : node[step]), answer);
+  if (typeof value !== "string") {
+    const found = value === undefined ? "nothing" : Array.isArray(value) ? "a list" : value === null ? "null" : `a ${typeof value}`;
+    return {
+      error: `slice.path ${path} names ${found} in this query's answer, not a text value.`,
+      hint: 'Pass a path from the answer\'s clipped notes, such as "data.article.body", with the same query and variables.',
+    };
+  }
+  const total = value.length;
+  const piece = (length) => {
+    const end = Math.min(total, offset + length);
+    const cut = end < total && /[\uD800-\uDBFF]/.test(value[end - 1]) ? end - 1 : end;
+    const text = value.slice(offset, cut);
+    const kept = offset + text.length;
+    return kept < total
+      ? { text, clipped: [{ path, kept, total }], hint: `Call again with slice: { path: "${path}", offset: ${kept} } for the rest.` }
+      : { text };
+  };
+  // The longest piece that fits, found by bisection: escapes make JSON longer than the text.
+  let low = 0;
+  let high = Math.max(0, total - offset);
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (JSON.stringify(piece(middle)).length <= maxChars) low = middle;
+    else high = middle - 1;
+  }
+  return piece(low);
+}
+
+export const GRAPHQL_TOOLS = [
+  {
+    name: "capa_graphql_schema",
+    ...reads("GraphQL schema"),
+    ...BOUNDED,
+    ...SCOPE,
+    description:
+      "Start here to query content. Without model: every model this key can read (namespace, name, type), its roots " +
+      "and REST path, fields as `name: Type` and relations as `field -> model` (->> for a list), and the key's " +
+      "scopes. With model: each field's filter operators, hops and sortability, the sort values and a runnable example. " +
+      "sdl adds the SDL. Next: capa_explore_data for real values, capa_graphql_build to write a query.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        model: { type: "string", description: 'Namespace, type or name, e.g. "articles". Omit for every model.' },
+        sdl: { type: "boolean", description: "Also return the SDL." },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: answerSchema({
+      version: { type: "string" },
+      key: { type: "object", description: "The key's environment, bundle and scopes." },
+      models: { type: "array" },
+      system: { type: "string" },
+      model: { type: "string" },
+      type: { type: "string" },
+      name: { type: "string" },
+      graphql: { type: ["object", "string"] },
+      rest: { type: "string" },
+      fields: { type: "array" },
+      sort: { type: "array", items: { type: "string" } },
+      example: { type: "object" },
+      media: { type: "string" },
+      sdl: { type: "string" },
+      alsoReferenced: { type: "array", items: { type: "string" } },
+      truncated: { type: ["array", "string"], description: "What was cut to fit; for the whole SDL, the models not printed." },
+    }),
+    handler: async (config, args) => {
+      const { introspection, summary } = await loadSchema(config);
+      if (args.model === undefined) return args.sdl ? wholeSDL(introspection, summary) : schemaMap(config, summary);
+      let model;
+      try {
+        model = findModel(summary, args.model);
+      } catch (error) {
+        if (error instanceof BuildError) return buildRefusal(error);
+        throw error;
+      }
+      const detail = modelDetail(summary, model, introspection);
+      if (args.sdl) return detailWithSDL(detail, introspection, summary, model);
+      return boundAnswer(detail, DEFAULT_MAX_CHARS, { hint: modelHint(model) });
+    },
+  },
+
+  {
+    name: "capa_graphql_build",
+    ...reads("Build a GraphQL query"),
+    ...BOUNDED,
+    ...SCOPE,
+    description:
+      "Write a query from an intent: model, fields (a relation as { field, fields }; omit for every non-relation " +
+      "field), filter, sort, first, and after a page's endCursor or before its startCursor or \"end\". Returns query, " +
+      "variables, operationName and rest (the REST twin). code adds @capacms/sdk code (next for a Next.js server " +
+      "component, node, rest, all): ask on the final build. It runs once: check says if it worked; run: true returns " +
+      'the data. filter takes the operators capa_graphql_schema { model } lists, e.g. { "views": { "gte": 10 } }. ' +
+      "Unknown names come back with didYouMean.",
+    inputSchema: {
+      type: "object",
+      required: ["model"],
+      properties: {
+        model: { type: "string" },
+        mode: { type: "string", enum: ["list", "single"] },
+        id: { type: "string", description: "Reads one entry by UUID." },
+        fields: {
+          type: "array",
+          description: 'e.g. ["title", { "field": "author", "fields": ["name"] }]',
+          items: {
+            anyOf: [
+              { type: "string" },
+              {
+                type: "object",
+                required: ["field"],
+                properties: {
+                  field: { type: "string" },
+                  fields: { type: "array" },
+                  first: { type: "integer", minimum: 1, maximum: 200 },
+                  sort: { type: ["string", "array"] },
+                },
+                additionalProperties: false,
+              },
+            ],
+          },
+        },
+        first: { type: "integer", minimum: 1, maximum: 200 },
+        after: { type: "string" },
+        before: { type: "string" },
+        sort: { type: ["string", "array"], items: { type: "string" }, maxItems: 3, description: "e.g. [\"views_DESC\"]" },
+        filter: { type: "object" },
+        totalCount: { type: "boolean" },
+        run: { type: "boolean" },
+        code: { type: "string", enum: ["none", "next", "node", "rest", "all"] },
+        maxChars: MAX_CHARS,
+      },
+      additionalProperties: false,
+    },
+    outputSchema: answerSchema({
+      query: { type: "string" },
+      variables: { type: "object" },
+      operationName: { type: "string" },
+      rest: { type: "string", description: "The REST twin, as the API prints it." },
+      restFromApi: { type: "string" },
+      sdk: { type: "object", description: "code's parts: document, next, node, rest." },
+      check: { type: "object", description: "Without run: whether a run worked." },
+      result: { type: "object", description: "With run: data, errors, cost, budget." },
+      more: { type: "array", description: "Relation lists holding more; next reads on." },
+      ...READ_WITH_KEYS,
+    }),
+    handler: async (config, args) => {
+      const { summary } = await loadSchema(config);
+      const { run, maxChars, code = "none", ...spec } = args;
+      let plan;
+      try {
+        plan = planQuery(summary, spec);
+      } catch (error) {
+        if (error instanceof BuildError) return buildRefusal(error);
+        throw error;
+      }
+      const built = printGraphQL(plan);
+      const rest = printRest(summary, plan);
+      const sdk = sdkCode(code, sdkSnippets(config, summary, plan, built, rest));
+      const answer = { ...built, rest: rest.url, ...(sdk ? { sdk } : {}) };
+      // Only the result is ever cut; the SDK code asked for goes whole first, as it comes back from a call without run.
+      // The run selects each list's cursors and every relation list's pageInfo (runWithCursors), so a cut list
+      // pages on from its last entry kept, and a relation list that holds more than it shows can say so.
+      const read = printGraphQL(plan, { cursors: true });
+      const connections = connectionsOf(read.query, built.variables, built.operationName, { at: "result.data" });
+      const bounded = (cursors = {}, listsOf = () => []) =>
+        boundWithMore(
+          (budget) =>
+            boundAnswer(answer, budget, { keep: BUILT_PARTS, drop: ["sdk"], cursors, connections, hint: BUILD_HINT, readOn: readOnFromBuild, fallbackHint: BUILD_FALLBACK_HINT }),
+          listsOf,
+          answer,
+          maxChars ?? DEFAULT_MAX_CHARS,
+          buildMoreNote,
+        );
+      let ran;
+      try {
+        ran = await runWithCursors(config, plan, built);
+      } catch (error) {
+        // The document is still what the agent asked for; the refusal is the check.
+        if (!(error instanceof QueryRefused)) throw error;
+        answer.check = { ok: false, status: error.status, errors: error.errors, ...fittingFirst(plan, error.errors), ...nextField(error.errors) };
+        return bounded();
+      }
+      const { result, cursors } = ran;
+      Object.assign(answer, readWith(result.environment, result.data, result.errors));
+      delete result.environment;
+      if (run) {
+        // The API's REST twin is the answer's `rest`, or `restFromApi` when they differ: not repeated here.
+        const { rest: _twin, ...data } = result;
+        answer.result = data;
+      } else {
+        const root = result.data?.[plan.mode === "single" ? plan.model.singleField : plan.model.listField];
+        answer.check = result.errors
+          ? { ok: false, errors: result.errors, ...nextField(result.errors) }
+          : {
+              ok: true,
+              entries: plan.mode === "single" ? (root ? 1 : 0) : root?.nodes?.length ?? 0,
+              ...(result.cost ? { cost: result.cost } : {}),
+              ...(result.budget ? { budget: result.budget } : {}),
+            };
+      }
+      const serverRest = result.rest?.[0]?.url;
+      if (serverRest && decodeURIComponent(serverRest) !== decodeURIComponent(rest.url)) answer.restFromApi = serverRest;
+      // A relation list that holds more than it shows is named, with the read that goes on (bin-250: 100 of 250).
+      // With run, it is read from the answer as cut; without, from the run the check made.
+      const listsIn = (data) =>
+        relationsWithMore(data, connections, "result.data").map((list) => {
+          const next = nextRead(plan, "result.data", list);
+          const { endCursor: _cursor, entry: _entry, ...shown } = list;
+          return { ...shown, path: run ? list.path : list.path.slice("result.".length), ...(next ? { next } : {}) };
+        });
+      const unrun = run ? null : listsIn(result.data);
+      const out = bounded(cursors, (cut) => unrun ?? listsIn(cut.result?.data));
+      if (out.result) withoutNestedPages(out.result.data, plan, { keepMore: !out.more });
+      return out;
+    },
+  },
+
+  {
+    name: "capa_graphql_query",
+    ...reads("Run a GraphQL query"),
+    ...BOUNDED,
+    ...SCOPE,
+    description:
+      "Run a GraphQL read: data, errors (each with code and hint), cost, budget and each root field's REST " +
+      "twin. No document yet? capa_graphql_build writes one. A large answer is cut, lists from their end " +
+      "(truncated says where) and long text (clipped says where; slice reads on): ask for fewer fields or a smaller " +
+      "first, not a larger maxChars. A refused query's error gives each code's fix and the next tool.",
+    inputSchema: {
+      type: "object",
+      required: ["query"],
+      properties: {
+        query: { type: "string", minLength: 1, description: "e.g. { articles(first: 5) { nodes { id title } } }" },
+        variables: { type: "object" },
+        operationName: { type: "string" },
+        slice: {
+          type: "object",
+          required: ["path"],
+          properties: { path: { type: "string" }, offset: { type: "integer", minimum: 0 } },
+          additionalProperties: false,
+        },
+        maxChars: MAX_CHARS,
+      },
+      additionalProperties: false,
+    },
+    outputSchema: answerSchema({
+      data: { type: ["object", "null"] },
+      errors: { type: "array", description: "Each { message, code, hint, path }." },
+      cost: { type: "object" },
+      budget: { type: "object" },
+      deprecations: { type: "array" },
+      rest: { type: "array", description: "Each root field's REST twin, { field, url }." },
+      more: { type: "array", description: "Relation lists holding more." },
+      text: { type: "string" },
+      ...READ_WITH_KEYS,
+    }),
+    // A cut list keeps a pageInfo true of what it kept (lib/bound.mjs), read from the document so an aliased
+    // connection and a page read backward are repaired too, and paging on from its cursor skips nothing. A
+    // relation list whose own page holds more than it shows is named in `more` (bin-250: 100 of 250).
+    handler: async (config, args) => {
+      const connections = connectionsOf(args.query, args.variables, args.operationName, { at: "data" });
+      const { environment, ...ran } = await runQuery(config, args.query, args.variables, args.operationName);
+      if (args.slice) return sliceOf(ran, args.slice, args.maxChars ?? DEFAULT_MAX_CHARS);
+      const result = { ...ran, ...readWith(environment, ran.data, ran.errors) };
+      return boundWithMore(
+        (budget) => boundAnswer(result, budget, { connections, spare: QUERY_SPARE, readOn: readOnWithSlice }),
+        (out) =>
+          relationsWithMore(out.data, connections, "data").map((list) => {
+            const next = queryNextRead(args, list);
+            return next ? { ...list, next } : list;
+          }),
+        result,
+        args.maxChars ?? DEFAULT_MAX_CHARS,
+        queryMoreNote,
+      );
+    },
+  },
+
+  {
+    name: "capa_explore_data",
+    ...reads("Explore a model's content"),
+    ...BOUNDED,
+    ...SCOPE,
+    description:
+      "Measure a model's real content before you filter, sort or change it: entries by status, and per field " +
+      "how many store a value, an empty one or none (as filters count), dangling references, mistyped " +
+      "values, ranges, enum-like values, list sizes and fan-out. field measures one field. Reads up to " +
+      "maxEntries (default 200), says if that is not all, and returns samples. For types use capa_graphql_schema; " +
+      "to fetch entries, capa_graphql_build.",
+    inputSchema: {
+      type: "object",
+      required: ["model"],
+      properties: {
+        model: { type: "string" },
+        field: { type: "string" },
+        sample: { type: "integer", minimum: 0, maximum: 10, description: "Default 3." },
+        maxEntries: { type: "integer", minimum: 1, maximum: 1000 },
+        maxChars: MAX_CHARS,
+      },
+      additionalProperties: false,
+    },
+    outputSchema: answerSchema({
+      model: { type: "string" },
+      environment: { type: "string" },
+      drafts: { type: "string" },
+      total: { type: ["integer", "null"] },
+      scanned: { type: "integer" },
+      statuses: { type: "object" },
+      counts: { type: "string", description: "What each count means; left out, after samples, of a cut answer." },
+      fields: { type: "array" },
+      samples: { type: "array" },
+      skipped: { type: "object" },
+      errors: { type: "array" },
+    }),
+    handler: async (config, args) => {
+      const { summary } = await loadSchema(config);
+      let model;
+      try {
+        model = findModel(summary, args.model);
+      } catch (error) {
+        if (error instanceof BuildError) return buildRefusal(error);
+        throw error;
+      }
+      let wanted = model.fields;
+      if (args.field !== undefined) {
+        wanted = model.fields.filter((f) => f.name === args.field || f.namespace === args.field);
+        if (!wanted.length) {
+          const names = model.fields.map((f) => f.name);
+          return { error: `unknown field ${args.field} on ${model.typeName}`, didYouMean: didYouMean(args.field, names), available: names };
+        }
+      }
+      const { measured: fields, skipped } = measurableFields(wanted);
+      const maxEntries = args.maxEntries ?? 200;
+      const query = exploreQuery(model, fields, Math.min(pageSizeFor(fields), maxEntries));
+      const nodes = [];
+      const stored = new Map();
+      const hidden = new Map();
+      const nullLists = new Map();
+      const lists = new Map();
+      let total = null;
+      let environment = null;
+      let after;
+      while (nodes.length < maxEntries) {
+        const body = await postQuery(config, query, after ? { after } : {}, "CapaExplore");
+        const errors = trimErrors(body.errors);
+        if (errors.length) return { error: "The exploration query failed.", errors, ...nextField(errors) };
+        // A development key reads drafts too, so the counts say which key made them.
+        environment ??= body.extensions?.capa?.environment ?? null;
+        const page = body.data?.[model.listField];
+        total ??= page?.totalCount ?? null;
+        const pageNodes = (page?.nodes ?? []).slice(0, maxEntries - nodes.length);
+        nodes.push(...pageNodes);
+        for (const [id, fieldsStored] of await readStored(config, model, fields, pageNodes)) stored.set(id, fieldsStored);
+        const pageIds = pageNodes.map((node) => node.id);
+        await readMatches(config, hiddenValueRequests(model, fields, stored, pageIds), hidden);
+        await readMatches(config, nullListRequests(model, fields, stored, pageIds), nullLists);
+        await readMatches(config, listRequests(model, fields, stored, pageIds), lists);
+        if (!page?.pageInfo?.hasNextPage) break;
+        after = page.pageInfo.endCursor;
+      }
+      const scanned = nodes;
+      const answer = {
+        model: model.namespace,
+        ...readWith(environment),
+        total,
+        scanned: scanned.length,
+        statuses: statusCounts(scanned),
+        counts: COUNTS_LEGEND,
+        fields: fields.map((f) => fieldStats(f, scanned, stored, hidden.get(f.namespace), nullLists.get(f.namespace), lists.get(f.namespace) ?? new Set())),
+        samples: samples(scanned, fields, args.sample ?? 3),
+      };
+      if (skipped.length) {
+        answer.skipped = {
+          fields: skipped.map((f) => f.name),
+          why: "One query expands at most 12 relations. Pass field to measure one of these.",
+        };
+      }
+      if (total !== null && scanned.length < total) {
+        answer.note = `Measured the first ${scanned.length} of ${total} entries in the API's default order. Raise maxEntries (up to 1000) for more.`;
+      }
+      // Every field's numbers are what was asked for: the samples, then the legend, go first when it does not fit.
+      return boundAnswer(answer, args.maxChars, { drop: EXPLORE_EXTRAS, hint: EXPLORE_HINT });
+    },
+  },
+
+  {
+    name: "capa_explain_error",
+    ...reads("Explain a Capa API error"),
+    ...BOUNDED,
+    surface: "local",
+    description:
+      "Explain a Capa API error from anywhere (a site's logs, the SDK, a paste) and what to change. Pass it as you got " +
+      "it (a GraphQL errors array, a REST error body, an SDK CapaError, or plain text), or just its code. Returns what " +
+      "the code means, the fix, the API's own hint, and the tool to call next. Errors from capa_graphql_query already " +
+      "carry their next step. Works offline, needs no scope, and never calls Capa.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        error: {
+          type: ["string", "object", "array"],
+          description: 'The error as received, e.g. { "errors": [...] } or "invalid_cursor: ...".',
+        },
+        code: { type: "string", description: 'Just the code, e.g. "query_too_complex".' },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: answerSchema({
+      errors: { type: "array", description: "Each { code, meaning, fix, next, docs }, with the API's own message and hint." },
+      more: { type: "integer" },
+      example: { type: "object" },
+    }),
+    handler: async (_config, args) => {
+      const items = [...normalizeErrors(args.error), ...(args.code ? [{ code: args.code }] : [])];
+      if (!items.length) {
+        return { error: "Pass error (the error as received) or code.", example: { code: "query_too_complex" } };
+      }
+      const explained = items.slice(0, 5).map(explainOne);
+      // A pasted log can be any length, and `message` echoes it.
+      return boundAnswer(items.length > 5 ? { errors: explained, more: items.length - 5 } : { errors: explained }, DEFAULT_MAX_CHARS, { hint: EXPLAIN_HINT });
+    },
+  },
+];