@capacms/mcp 0.2.0

package/lib/tools.mjs

@@ -0,0 +1,1158 @@
+/**
+ * tools.mjs — the tool set.
+ *
+ * #4583 is explicit that this must NOT be a thin wrapper exposing every
+ * endpoint: "a deliberately shaped tool set that gets an agent to the right
+ * context fast". So the shaping rules, stated because the next person to add a
+ * tool needs them:
+ *
+ *   1. A tool exists to answer a QUESTION an agent has, not to mirror a route.
+ *      `capa_get_model` answers "what shape is this content?" — it does not
+ *      correspond to any single endpoint.
+ *   2. Every tool trims. /v2/schema returns 20 models with every field, which
+ *      is thousands of tokens an agent mostly does not need; `capa_list_models`
+ *      returns names and counts, and `capa_get_model` returns the detail for
+ *      one. Two calls beats one huge one.
+ *   3. Filtering happens server-side wherever the API supports it, and in this
+ *      file where it does not — an agent should never have to fetch everything
+ *      to find one thing.
+ *
+ * MOSTLY READ, AND NO LONGER READ-ONLY. The three `capa_*_workspace` tools at
+ * the bottom write, through `/v2/agent/workspaces` (ADMIN_UI_OVERHAUL 0h.4b).
+ * They need a key with `write` permission and surface the API's own 403 when
+ * the key has only `read` — see the corrected note in client.mjs, which used to
+ * claim no write verb existed behind a key at all.
+ *
+ * The rest of #4583's write half (edit content, validate, publish) still needs
+ * tools of its own against `/v2/agent/model-instances`. Absent rather than
+ * stubbed, because a tool that always fails teaches an agent to stop trying.
+ *
+ * WHY /v2/seo/ai-bundle IS NOT A TOOL, having been measured rather than assumed
+ * It is API-key reachable and the source calls it a "RAG-ready export across
+ * every model", so it looks like an obvious fit. It is not. On one ordinary
+ * tenant (20 models, 664 documents) it returns:
+ *
+ *     1,624,988 bytes  —  roughly 406,000 tokens
+ *
+ * That does not fit in any context window, and bounding it does not rescue it:
+ * at limit=1 the schemas block alone is 16.7 KB before a single document. The
+ * endpoint is built for a RAG INGESTION pipeline, which reads once and writes
+ * to a vector store — not for an agent's context, which is the resource rule 2
+ * above exists to protect.
+ *
+ * If we do want it, the right shape is a tool that WRITES THE BUNDLE TO A FILE
+ * and returns the path, so the bytes never enter the conversation. That is a
+ * different tool with a different contract, and it should be built deliberately
+ * rather than by pointing a `capa_get_*` at a large endpoint.
+ *
+ * TWO SURFACES, AND EVERY TOOL SAYS WHICH IT IS ON.
+ *
+ * `surface: "legacy"` means the tool calls `/v2/*` or `/v3/*`, which a `pk_` or
+ * `sk_` key reaches and a `cap_` key is refused on before any lookup.
+ * `surface: "api"` means it calls `/api/`, which both families reach.
+ * `lib/registry.mjs` turns those two words into the tool list one key actually
+ * gets, so an agent is never offered a tool its key cannot use.
+ *
+ * An `api` tool also declares the `scope` it needs. `/api/me` reports the
+ * scopes a key holds, and a tool whose scope is missing from that list is left
+ * out rather than registered and refused. The field is a string compared
+ * whole: the page routes ask for UNSCOPED `instance:read`, so a key holding
+ * only `instance:read:<modelId>` does not get them, which is the same answer
+ * the API would give.
+ */
+import { reads, writes } from "./annotations.mjs";
+import { DEFAULT_MAX_CHARS, someNames } from "./bound.mjs";
+import { apiGet, apiGetText, apiNextGet, apiWrite, CapaApiError } from "./client.mjs";
+import { GRAPHQL_TOOLS } from "./graphql-tools.mjs";
+import { REST_TOOLS } from "./rest-tools.mjs";
+
+/**
+ * The legacy tools name a model `namespace`, as `/v2` does; the GraphQL tools
+ * teach `model`, so either is read (server.mjs `withAliases`).
+ */
+const MODEL_ALIAS = { aliases: { model: "namespace" } };
+
+/** What a types answer cut to the budget tells the agent. */
+const TYPES_HINT = "Pass namespace for one model's interface and the types it uses.";
+const typeNameOf = (block) => (/^export (?:interface|type) (\w+)/m.exec(block) || [])[1];
+
+/**
+ * The types answer for `blocks` of generated TypeScript, cut between whole
+ * declarations when it is over the answer budget: half a declaration does not
+ * compile, and a clipped string of source is worse than none. `bytes` is the
+ * size of everything asked for, and `notPrinted` names what was left out.
+ */
+function typesAnswer(blocks, extra = {}) {
+  const source = blocks.join("\n");
+  const whole = { source, bytes: source.length, ...extra };
+  if (JSON.stringify(whole).length <= DEFAULT_MAX_CHARS) return whole;
+  const cut = (count) => ({
+    ...whole,
+    source: blocks.slice(0, count).join("\n"),
+    truncated: [{ path: "source", kept: count, total: blocks.length }],
+    notPrinted: someNames(blocks.slice(count).map(typeNameOf).filter(Boolean)),
+    hint: TYPES_HINT,
+  });
+  // The serialized size grows with the count, so the largest count that fits is found by bisection.
+  let fits = 0;
+  let over = blocks.length;
+  while (over - fits > 1) {
+    const middle = (fits + over) >> 1;
+    if (JSON.stringify(cut(middle)).length <= DEFAULT_MAX_CHARS) fits = middle;
+    else over = middle;
+  }
+  return cut(fits);
+}
+
+/** /v2/schema is the one call that describes everything; cache it per process. */
+let schemaCache = null;
+export function __resetSchemaCacheForTests() {
+  schemaCache = null;
+}
+async function schema(config) {
+  if (!schemaCache) schemaCache = await apiGet(config, "/v2/schema");
+  return schemaCache;
+}
+
+const lc = (s) => String(s ?? "").toLowerCase();
+
+/**
+ * Capa stores most values as `{ type, value, sortOrder }` rather than bare
+ * scalars — including `title`, which reads like a plain column and is not.
+ *
+ * Handing an agent `{"type":"string","value":"Influencers and Ambassadors",
+ * "sortOrder":0}` where it expected a title is three times the tokens and
+ * invites it to reach for `.value` itself, which it will then do inconsistently.
+ *
+ * Found by driving the server against real data: the unit test's fake row had
+ * `title: "Hello"`, a plain string, so it passed. The fake was more uniform
+ * than production — the same failure this repo documented in
+ * docs/P2_DATA_IN.md §8 about the seed, reproduced in a test fixture within
+ * hours of writing that section down.
+ */
+const unwrap = (v) =>
+  v && typeof v === "object" && !Array.isArray(v) && "value" in v ? v.value : v ?? null;
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The instance id.
+ *
+ * `instanceId` FIRST, for the day a server sends it. No server does today:
+ * #4628 added it to every row of `/v2/api/:ns` and the public-surface freeze
+ * reverted that on 2026-09-20 (PARITY_EXCEPTIONS.md #22), because that surface
+ * answers the bytes the legacy API answers and a key like this ships on the
+ * next API version. So the fallback below is what actually runs.
+ *
+ * `id` is the fallback, and it is a fallback because it is not trustworthy. The
+ * route builds each row as `{...instance, ...formatInstanceData(instance)}`. The
+ * model's own fields are hoisted to the top level and spread SECOND, so a field
+ * named `id` OVERWRITES the instance's id and the real UUID then appears nowhere
+ * in the row. Same for `title` and `tags`. In one ordinary tenant, 20 of 20
+ * models have a field named `title` and 7 of 20 have one named `id` (every
+ * shopify_* model, plus judge_me_review), so this is the common case, and the
+ * UUID test is what separates an instance id from a Shopify numeric id sitting
+ * in a field called `id` on a server that predates the fix.
+ *
+ * null means neither was usable: a shadowing model on a server that sends no
+ * `instanceId`, which is every server today. The first
+ * version of these tools returned `row.id` raw, so capa_list_content handed back
+ * {"type":"string","value":"41269952589"} as an id and the capa_get_content call
+ * it invites 400ed. Returning null and saying why beats returning something that
+ * looks like an id and is not.
+ */
+const instanceIdOf = (row) => {
+  if (typeof row?.instanceId === "string" && UUID_RE.test(row.instanceId)) return row.instanceId;
+  return typeof row?.id === "string" && UUID_RE.test(row.id) ? row.id : null;
+};
+
+export const TOOLS = [
+  {
+    name: "capa_list_models",
+    ...reads("List content models"),
+    cutHint: "Pass search to list only the models whose namespace or name matches.",
+    surface: "legacy",
+    description:
+      "List the content models in this Capa tenant: namespace, human name, field count, " +
+      "and what each one relates to, from the legacy /v2 API. Returns names only; use " +
+      "capa_get_model for one model's fields. To write or run a query against content, start " +
+      "from capa_graphql_schema instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        search: {
+          type: "string",
+          description: "Case-insensitive substring match on namespace or name. Omit to list all.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const s = await schema(config);
+      const relByFrom = new Map();
+      for (const r of s.relations ?? []) {
+        if (!relByFrom.has(r.fromModel)) relByFrom.set(r.fromModel, []);
+        relByFrom.get(r.fromModel).push(`${r.fromField} -> ${r.toModel ?? "(dangling)"}`);
+      }
+      const q = lc(args.search);
+      const models = (s.models ?? [])
+        .filter((m) => !q || lc(m.namespace).includes(q) || lc(m.modelName).includes(q))
+        .map((m) => ({
+          namespace: m.namespace,
+          name: m.modelName,
+          singleInstance: m.isSingleInstance,
+          fieldCount: (m.fields ?? []).length,
+          relatesTo: relByFrom.get(m.namespace) ?? [],
+        }));
+      return { models, total: models.length, checksum: s.checksum };
+    },
+  },
+
+  {
+    name: "capa_get_model",
+    ...reads("Get a model and its editor layout"),
+    whole: true,
+    surface: "legacy",
+    ...MODEL_ALIAS,
+    description:
+      "Full field definitions for ONE model as the editor sees them: every field's namespace, " +
+      "type, whether it is required, what a relation points at, and the editor layout. Use it " +
+      "before capa_set_model_layout or to check required fields. To query the model's content, " +
+      "capa_graphql_schema { model } gives the names a query takes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        namespace: { type: "string", description: "The model's namespace, e.g. \"blog_post\"." },
+      },
+      required: ["namespace"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const s = await schema(config);
+      const model = (s.models ?? []).find((m) => m.namespace === args.namespace);
+      if (!model) {
+        const near = (s.models ?? [])
+          .map((m) => m.namespace)
+          .filter((n) => lc(n).includes(lc(args.namespace)) || lc(args.namespace).includes(lc(n)));
+        return {
+          error: `No model with namespace "${args.namespace}".`,
+          // A bare "not found" makes an agent guess again; naming the near
+          // misses and the full list lets it correct in one step.
+          didYouMean: near,
+          available: (s.models ?? []).map((m) => m.namespace),
+        };
+      }
+
+      // A SECOND request, for the two things /v2/schema does not carry: the
+      // field IDS and the entry-editor LAYOUT (ADMIN_UI_OVERHAUL 0m.4).
+      //
+      // They travel together because they are useless apart: a layout places
+      // fields by id, so an agent handed a layout and no ids can read the page
+      // but not change it. One extra GET for one model is the cost of
+      // capa_set_model_layout being usable at all, and it is not paid by
+      // capa_list_models, which stays one call for the whole tenant.
+      let detail = null;
+      let unavailable;
+      try {
+        detail = await apiGet(config, `/v2/agent/models/${encodeURIComponent(model.namespace)}`);
+      } catch (error) {
+        // Reported rather than swallowed: `layout: null` means LINEAR, and
+        // saying that when the truth is "this key could not read it" would send
+        // an agent off to build a layout that is about to collide with one.
+        unavailable =
+          error instanceof CapaApiError
+            ? `Field ids and layout are unavailable: ${error.message}`
+            : String(error?.message ?? error);
+      }
+      const idByNamespace = new Map(
+        (detail?.fields ?? []).map((f) => [f.namespace, f.id]),
+      );
+
+      return {
+        namespace: model.namespace,
+        name: model.modelName,
+        singleInstance: model.isSingleInstance,
+        fields: (model.fields ?? []).map((f) => ({
+          // The id a layout node's `fieldId` has to be. Absent only when the
+          // detail call failed, which `layoutUnavailable` then says.
+          id: idByNamespace.get(f.namespace),
+          namespace: f.namespace,
+          name: f.name,
+          type: f.arrayType ? `${f.type}<${f.arrayType}>` : f.type,
+          required: f.required,
+          relatesTo: f.relationRef ?? undefined,
+          enumValues: f.enumValues ?? undefined,
+        })),
+        relations: (s.relations ?? []).filter((r) => r.fromModel === model.namespace),
+        // null = the linear editor, which is what a model without a designed
+        // page gets. Write it with capa_set_model_layout.
+        //
+        // ABSENT rather than null when the detail call failed. null is a claim
+        // — "this model has no page" — and emitting it for "this key could not
+        // read it" is the exact mistake the catch above exists to avoid. An
+        // agent that finds no `layout` key cannot read the failure as an
+        // answer; `layoutUnavailable` then says which failure it was.
+        ...(detail ? { layout: detail.layout ?? null } : {}),
+        // 0m.8. TRUE means a relation field pointing at THIS model renders its
+        // fields inside the parent form rather than as a picker, wherever the
+        // layout node does not say otherwise — including in linear mode. An
+        // agent laying out a parent needs it to know what a relation node with
+        // no `display` will actually do. Absent for the same reason `layout`
+        // is when the detail call failed: `false` is a claim.
+        ...(detail ? { embedByDefault: detail.embedByDefault === true } : {}),
+        ...(unavailable ? { layoutUnavailable: unavailable } : {}),
+      };
+    },
+  },
+
+  {
+    name: "capa_set_model_layout",
+    ...writes("Set a model's editor layout", { idempotent: true }),
+    whole: true,
+    surface: "legacy",
+    aliases: { model: "modelId" },
+    description:
+      "Design a model's entry editor: cards in a main column and a side column, with each field " +
+      "placed in one of them. WRITES: it needs an API key whose permission is `agent`. Pass " +
+      "layout: null to reset the model to the plain linear editor. The document is " +
+      "{ v: 1, main: Card[], aside: Card[] } where a Card is { id, title, description?, " +
+      "collapsible, collapsed, items: Field[] } and a Field is { id, fieldId, width, display?, " +
+      "inline? }. `id` is any id you choose, unique in the document; `fieldId` is the field's id " +
+      "from capa_get_model. Widths are full, two_thirds, half or third. Relation fields may take " +
+      "display \"picker\", \"inline\" or \"embedded\" (embedded draws the related entry's own " +
+      "fields directly in the parent card), plus inline { allowCreate, allowRemove, " +
+      "allowReorder, summary } where summary is up to 3 field ids OF THE RELATED model. Leave " +
+      "display out and the related model's own embedByDefault decides, which capa_get_model " +
+      "reports. Read the current one with capa_get_model first: it returns the same document, " +
+      "so you can edit and write it back.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        modelId: {
+          type: "string",
+          description: "The model's id, or its namespace; either works.",
+        },
+        layout: {
+          type: ["object", "null"],
+          description:
+            "The layout document, or null to reset the model to the linear editor.",
+          additionalProperties: true,
+        },
+      },
+      required: ["modelId", "layout"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const path = `/v2/agent/models/${encodeURIComponent(args.modelId)}/layout`;
+      try {
+        const res = await apiWrite(config, "PUT", path, { layout: args.layout ?? null });
+        return { layout: res?.layout ?? null };
+      } catch (error) {
+        if (error instanceof CapaApiError && error.status === 400) {
+          // The API's rejection names the offending node —
+          // "main[0].items[2].fieldId" — and that path is the whole value of
+          // the message to an agent about to try again. Passed through as
+          // fields rather than buried in a thrown string.
+          let body = null;
+          try {
+            body = JSON.parse(error.body);
+          } catch {
+            body = null;
+          }
+          return {
+            error: body?.error ?? error.message,
+            path: body?.path,
+            hint:
+              "Fix the node named by `path` and send the document again. Field ids come from " +
+              "capa_get_model; a field can appear at most once in the whole layout.",
+          };
+        }
+        if (error instanceof CapaApiError && error.status === 403) {
+          return {
+            error: error.message,
+            hint:
+              "This tool writes a model, so it needs a Capa API key whose permission is `agent`. " +
+              "`read`, `write` and `delete` keys can call capa_get_model but not this one.",
+          };
+        }
+        throw error;
+      }
+    },
+  },
+
+  {
+    name: "capa_list_content",
+    ...reads("List entries (legacy API)"),
+    cutHint: "Ask for a smaller limit or fewer fields, and page on with page.",
+    surface: "legacy",
+    ...MODEL_ALIAS,
+    description:
+      "List published content instances for a model, with paging. Returns a trimmed summary " +
+      "per item (id, title, and the fields you name) rather than whole documents; ask for " +
+      "capa_get_content when you need one in full. To filter, sort or follow relations, use " +
+      "capa_graphql_build.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        namespace: { type: "string", description: "Model namespace to list." },
+        limit: { type: "number", description: "Max items (default 20, server caps apply)." },
+        page: { type: "number", description: "1-based page number." },
+        fields: {
+          type: "array",
+          items: { type: "string" },
+          description: "Field namespaces to include in each summary. Omit for id + title only.",
+        },
+      },
+      required: ["namespace"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const res = await apiGet(config, `/v2/api/${encodeURIComponent(args.namespace)}`, {
+        limit: args.limit ?? 20,
+        page: args.page,
+        depth: 1,
+      });
+      const want = Array.isArray(args.fields) ? args.fields : [];
+      let shadowed = 0;
+      const items = (res.data ?? []).map((row) => {
+        const id = instanceIdOf(row);
+        if (id === null) shadowed++;
+        const out = { id, title: unwrap(row.title) };
+        if (id === null) out.idUnavailable = unwrap(row.id);
+        for (const f of want) out[f] = unwrap(row?.data?.[f]);
+        return out;
+      });
+      const out = { items, meta: res.meta };
+      if (shadowed) {
+        // Said once per call rather than per row. It does NOT name
+        // capa_search_content as a way out: that tool sends extended=true, and
+        // the extended search path hoists the model's own fields exactly as
+        // this one does, so it is shadowed in precisely the same cases.
+        out.warning =
+          `${shadowed} of ${items.length} rows have no usable id: the model "${args.namespace}" ` +
+          `has a field named "id", which overwrites the instance id in this endpoint's response, ` +
+          `and the public read API sends no \`instanceId\` alongside it (#4628 was reverted ` +
+          `under the public-surface freeze). capa_get_content cannot be called for these rows. ` +
+          `The value shown as idUnavailable is the model's own id field, not a Capa id.`;
+      }
+      return out;
+    },
+  },
+
+  {
+    name: "capa_get_content",
+    ...reads("Get one entry (legacy API)"),
+    cutHint: "Ask for a smaller depth: each level of relations adds every related entry in full.",
+    surface: "legacy",
+    ...MODEL_ALIAS,
+    description:
+      "One content instance in full, including related content up to the depth you ask for. " +
+      "Use after capa_list_content has told you which id you want.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        namespace: { type: "string", description: "Model namespace." },
+        id: { type: "string", description: "The instance id." },
+        depth: {
+          type: "number",
+          description: "How many relation hops to follow (default 1). Higher is much larger.",
+        },
+      },
+      required: ["namespace", "id"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      // Fail here rather than spending a request on a guaranteed 400. The ids
+      // capa_list_content can return for a shadowing model are the model's own
+      // id field, which is not a UUID and which the API rejects. See #4628.
+      if (!UUID_RE.test(String(args.id ?? ""))) {
+        return {
+          error: `"${args.id}" is not a Capa instance id.`,
+          hint:
+            `Capa instance ids are UUIDs. If capa_list_content returned this value, the model ` +
+            `has a field named "id" that overwrites the instance id in that endpoint's response ` +
+            `and the public read API sends no \`instanceId\` beside it (#4628 was reverted under ` +
+            `the public-surface freeze). capa_search_content is NOT a way around this: it sends ` +
+            `extended=true and the extended search path hoists the same fields the same way. ` +
+            `There is no way to recover the instance id from a public read response for a model ` +
+            `that shadows \`id\`; use the admin API, or wait for the next API version.`,
+        };
+      }
+      const res = await apiGet(config, `/v2/api/${encodeURIComponent(args.namespace)}`, {
+        ids: args.id,
+        depth: args.depth ?? 1,
+        limit: 1,
+      });
+      const item = (res.data ?? [])[0];
+      if (!item) return { error: `No instance ${args.id} in model "${args.namespace}".` };
+      return { item, relations: res.relations };
+    },
+  },
+
+  {
+    name: "capa_search_content",
+    ...reads("Search content"),
+    cutHint: "Ask for a smaller limit, or pass namespace to search one model.",
+    surface: "legacy",
+    ...MODEL_ALIAS,
+    description:
+      "Full-text search across this tenant's content, optionally within one model. Use when " +
+      "you know roughly WHAT you are looking for but not which model or id it lives in. " +
+      "When you know the model, capa_graphql_build filters it by field instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "The search text. Required and must be non-empty." },
+        namespace: {
+          type: "string",
+          description: "Restrict to one model namespace. Omit to search everything.",
+        },
+        limit: { type: "number", description: "Max results (default 20, server caps at 500)." },
+        page: { type: "number", description: "1-based page number." },
+      },
+      required: ["q"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      // A missing q answers 500 with an internal message on the server. #4627
+      // made it a 400 and the public-surface freeze put the 500 back on
+      // 2026-09-20. The check stays here because an agent should get a usable
+      // answer without spending a call.
+      const q = String(args.q ?? "").trim();
+      if (!q) {
+        return { error: "q is required and must be non-empty.", results: [], meta: null };
+      }
+      // extended=true, for two reasons. The default branch answers
+      // `{id, title}` and says nothing about which model a hit belongs to, so a
+      // result cannot be fed back into capa_get_content, which needs a
+      // namespace. (#4627 briefly added one; the public-surface freeze reverted
+      // it on 2026-09-20.) And the default branch reads the title out of the
+      // search DOCUMENT, which only ever holds `data.title.value`
+      // (search/indexes.ts buildInstanceDocument), so any model whose display
+      // field is not literally named `title` comes back with an EMPTY string.
+      // Observed against the seed's `authors` model, whose field is `name`:
+      // {"id":"...0011","title":""}, while the same instance under
+      // extended=true is "Ada Vale".
+      const res = await apiGet(config, "/v2/api/search", {
+        q,
+        modelNamespace: args.namespace,
+        size: args.limit ?? 20,
+        page: args.page,
+        extended: true,
+        depth: 0,
+      });
+      // Trimmed for the same reason as capa_list_content: a search result is a
+      // pointer, and the agent follows it with capa_get_content when it matters.
+      //
+      // instanceIdOf, NOT row.id. `extended=true` hoists the model's own fields
+      // over the row exactly as the content endpoints do, so for a model with a
+      // field named `id` this row's `id` is that field's value, not a UUID. No
+      // server sends `instanceId` on these rows today (#4628 was reverted under
+      // the public-surface freeze), so this is null for a shadowing model, the
+      // same as capa_list_content.
+      let shadowed = 0;
+      const results = (res.data ?? []).map((row) => {
+        const id = instanceIdOf(row);
+        if (id === null) shadowed++;
+        const out = {
+          id,
+          namespace: row.dataModel?.namespace ?? row.modelNamespace ?? null,
+          model: row.dataModel?.modelName ?? undefined,
+          title: unwrap(row.title),
+        };
+        if (id === null) out.idUnavailable = unwrap(row.id);
+        return out;
+      });
+      const out = { results, meta: res.meta };
+      if (shadowed) {
+        out.warning =
+          `${shadowed} of ${results.length} results have no usable id: the matched model ` +
+          `has a field named "id", which overwrites the instance id in this endpoint's ` +
+          `response, and this server is old enough not to send \`instanceId\` alongside it ` +
+          `(#4628). capa_get_content cannot be called for these results. ` +
+          `The value shown as idUnavailable is the model's own id field, not a Capa id.`;
+      }
+      return out;
+    },
+  },
+
+  {
+    name: "capa_get_types",
+    ...reads("Get TypeScript types (legacy API)"),
+    cutHint: TYPES_HINT,
+    surface: "legacy",
+    ...MODEL_ALIAS,
+    description:
+      "The generated TypeScript type definitions for this tenant's models, as source text: " +
+      "the exact interfaces the legacy /v2 API returns content as. Use when writing code " +
+      "against /v2. Code on @capacms/sdk/next reads a different shape: take the sdk code " +
+      "capa_graphql_build writes instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        namespace: {
+          type: "string",
+          description:
+            "Return only the interface for this model (plus the shared Capa* helpers). " +
+            "Omit for the whole file.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      // text/plain, not JSON — see apiGetText.
+      const source = await apiGetText(config, "/v2/schema/types");
+      const blocks = source.split(/\n(?=export (?:interface|type) )/);
+      if (!args.namespace) return typesAnswer(blocks);
+
+      const nameOf = typeNameOf;
+      const byName = new Map(blocks.map((b) => [nameOf(b), b]).filter(([n]) => n));
+      const wanted = lc(args.namespace).replace(/[^a-z0-9]/g, "");
+      const shared = blocks.filter((b) => /^export (interface|type) Capa/m.test(b));
+      const match = blocks.filter((b) => {
+        const n = nameOf(b);
+        return n && lc(n).replace(/[^a-z0-9]/g, "") === wanted && !/^Capa/.test(n);
+      });
+      if (!match.length) {
+        const names = blocks
+          .map((b) => (/^export (?:interface|type) (\w+)/m.exec(b) || [])[1])
+          .filter(Boolean);
+        return {
+          error: `No type for "${args.namespace}".`,
+          didYouMean: names.filter((n) => lc(n).includes(wanted) || wanted.includes(lc(n))),
+          available: names,
+        };
+      }
+      // Follow referenced type names transitively. BlogsHomeSection refers to
+      // ShopifyArticle[] and Link; returning it alone hands an agent a fragment
+      // that cannot compile, which is worse than returning the whole file.
+      // Found by reading the output rather than the code — the first version of
+      // this tool shipped the claim "still typechecks on its own" in a comment
+      // directly above the code that made it false.
+      const closure = new Map();
+      const queue = match.map(nameOf);
+      while (queue.length) {
+        const n = queue.shift();
+        if (!n || closure.has(n)) continue;
+        const block = byName.get(n);
+        if (!block) continue;
+        closure.set(n, block);
+        for (const ref of block.matchAll(/\b([A-Z]\w*)\b/g)) {
+          if (byName.has(ref[1]) && !closure.has(ref[1])) queue.push(ref[1]);
+        }
+      }
+      const ordered = [...shared.filter((b) => !closure.has(nameOf(b))), ...closure.values()];
+      return typesAnswer(ordered, { types: [...closure.keys()] });
+    },
+  },
+
+  // --------------------------------------------- saved workspaces (0h, 0t) ---
+  //
+  // A workspace is one saved arrangement of the admin's left rail: which
+  // models, entries and media folders a person or a team keeps in reach, in
+  // which folders, in which order. ADMIN_UI_OVERHAUL 0h.4b asks for exactly
+  // three tools — list, get, set — and for get/set to speak the SAME JSON
+  // document, "so an agent can read, edit and write back".
+  //
+  // That is the shaping rule here: `capa_get_workspace` does NOT return the
+  // rail's render tree (counts, statuses, per-folder item caps) because an
+  // agent cannot write that back. It returns the document, which is the thing
+  // that round-trips.
+  //
+  // §0t made the document ONE list. It was `{ model, content, media }`, three
+  // trees that could not hold each other's nodes; a folder now holds any kind,
+  // so the document is `tree: Node[]` and a folder is named by the customer
+  // rather than by us. The three-key shape is still accepted for one release
+  // and maps onto folders called Models, Content and Media, so an agent that
+  // learned the old shape keeps working while it is updated.
+
+  {
+    name: "capa_list_workspaces",
+    ...reads("List workspaces"),
+    cutHint: "Name the workspace you want and read it with capa_get_workspace.",
+    surface: "legacy",
+    description:
+      "List this tenant's saved workspaces: the arrangements of the Capa admin's left rail. " +
+      "Each one is a named tree of models, entries and media folders. Start here before " +
+      "capa_get_workspace or capa_set_workspace: it is where the ids come from, and it says " +
+      "which one is the tenant default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        includePrivate: {
+          type: "boolean",
+          description:
+            "Also list workspaces individual people made for themselves. Off by default: " +
+            "those are personal, and an agent almost always wants the team ones.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const res = await apiGet(config, "/v2/agent/workspaces", {
+        all: args.includePrivate ? "true" : undefined,
+      });
+      return {
+        workspaces: (res.workspaces ?? []).map((w) => ({
+          id: w.id,
+          name: w.name,
+          visibility: w.visibility,
+          isDefault: w.isDefault,
+          nodes: w.nodeCount,
+        })),
+        defaultId: res.defaultId ?? null,
+      };
+    },
+  },
+
+  {
+    name: "capa_get_workspace",
+    ...reads("Get a workspace document"),
+    whole: true,
+    surface: "legacy",
+    description:
+      "One workspace as a JSON document you can edit and write back with capa_set_workspace. " +
+      "The tree is `Node[]`, where a Node is `{folder, children?}`, `{model}`, `{instance}` or " +
+      "`{media_folder}`. A folder is named by the customer and holds any mix of the three, so " +
+      "there are no fixed sections. Models come back as NAMESPACES, so you can read and " +
+      "rearrange without resolving ids first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The workspace id, from capa_list_workspaces." },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) =>
+      apiGet(config, `/v2/agent/workspaces/${encodeURIComponent(args.id)}/document`),
+  },
+
+  {
+    name: "capa_set_workspace",
+    ...writes("Create or apply a workspace", { idempotent: false }),
+    cutHint: "The write is done; capa_get_workspace reads the whole document.",
+    surface: "legacy",
+    description:
+      "Create a workspace, or apply a document to one that exists. WRITES: it needs an API key " +
+      "with write permission. `mode: \"replace\"` makes the workspace exactly the document you " +
+      "send; `mode: \"merge\"` adds what is missing and removes nothing. Applying the same " +
+      "document twice changes nothing, so it is safe to retry. It never touches a record: a " +
+      "workspace is navigation, and removing something from it does not delete it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "The workspace to apply to. Omit to CREATE one, in which case name is required.",
+        },
+        name: { type: "string", description: "Name for a new workspace, or a rename for an existing one." },
+        mode: {
+          type: "string",
+          enum: ["replace", "merge"],
+          description: 'Default "merge", the safe one. "replace" removes anything the document does not name.',
+        },
+        template: {
+          type: "string",
+          enum: ["blank", "website", "catalog"],
+          description:
+            'Folders to start a NEW workspace with. "blank" (the default) makes none; ' +
+            '"website" makes Pages, Components, Settings, Media; "catalog" makes Products, ' +
+            "Collections, Assets. Ignored when applying to a workspace that already exists.",
+        },
+        tree: {
+          type: "array",
+          description:
+            'Node[]. A Node is { folder: "<name>", children?: Node[] }, ' +
+            '{ model: "<namespace or id>" }, { instance: "<id>" } or ' +
+            '{ media_folder: "<folder id>" }. A folder holds any mix of the three. ' +
+            "The old three-key shape { model, content, media } is still accepted for one " +
+            "release and lands in folders called Models, Content and Media.",
+          items: { type: "object", additionalProperties: true },
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const mode = args.mode ?? "merge";
+      const body = {};
+      if (args.name !== undefined) body.name = args.name;
+      if (args.tree !== undefined) body.tree = args.tree;
+
+      try {
+        if (!args.id) {
+          if (!args.name) {
+            return { error: "name is required when creating a workspace (omit id to create one)." };
+          }
+          // A key has no person behind it, so the API refuses a private
+          // workspace from this surface; saying so up front beats a 400.
+          if (args.template !== undefined) body.template = args.template;
+          const created = await apiWrite(config, "POST", "/v2/agent/workspaces", { ...body, visibility: "team" });
+          return { created: true, workspace: created.workspace, changes: created.changes ?? null, unresolved: created.unresolved ?? [] };
+        }
+        const applied = await apiWrite(
+          config,
+          "PUT",
+          `/v2/agent/workspaces/${encodeURIComponent(args.id)}/tree`,
+          { ...body, mode },
+        );
+        return {
+          created: false,
+          workspace: applied.workspace,
+          // The summary is the point of the call: an agent reads it to find out
+          // whether it actually changed anything, and a no-op says so.
+          changes: applied.changes,
+          unresolved: applied.unresolved ?? [],
+        };
+      } catch (error) {
+        // The API's OWN message, not a guess at it. A 403 here means the key
+        // may read and not write, which is a configuration fact somebody can
+        // act on — replacing it with "permission denied" would hide the fix.
+        if (error instanceof CapaApiError && error.status === 403) {
+          return {
+            error: error.message,
+            hint:
+              "This tool writes, so it needs a Capa API key whose permission is `write` " +
+              "(or `agent`). A `read` key can call capa_list_workspaces and capa_get_workspace " +
+              "but not this one.",
+          };
+        }
+        throw error;
+      }
+    },
+  },
+
+  // ------------------------------------------------------- pages (/api/) ---
+  //
+  // A page is a string starting with `/` that Capa learned about in one of two
+  // ways, and the union is the whole feature:
+  //
+  //   DECLARED — a model carries a route (`/blog/[slug]`, `/pricing`). It
+  //              exists with zero traffic, because a route somebody just set up
+  //              should be visible immediately rather than after a visitor.
+  //   OBSERVED — a read arrived carrying the page as the `Capa-Page` header. It
+  //              exists whether or not any model declares it, because most
+  //              sites have pages Capa knows nothing about.
+  //
+  // The two join on the string, so a page present in both is `kind: "both"`.
+  // `docs/api/pages.md` is the contract these three tools read.
+  //
+  // WHY AN AGENT WANTS THEM. Asked to change `/pricing`, an agent otherwise has
+  // to guess which models render it. `capa_get_page` answers that with the
+  // models, the entries and the exact queries the page issued, which is the
+  // difference between editing the right content and editing content that looks
+  // like it.
+  //
+  // NOTHING HERE COMPUTES A SUGGESTION. The rules that read a page's queries
+  // and say "this one fetches more than it renders" run on the API, so the Capa
+  // admin and an agent read one answer rather than two implementations that
+  // drift. This package has no dependencies and could not parse a select
+  // anyway. `capa_suggest_queries` passes those rows through verbatim and says
+  // so when there are none.
+
+  {
+    name: "capa_list_pages",
+    ...reads("List pages"),
+    cutHint: "Pass entry to list only the pages that read one entry.",
+    surface: "api",
+    scope: "instance:read",
+    feature: "pages",
+    description:
+      "Every page this Capa project knows about, busiest first: the page path, which content " +
+      "models it reads, and how many times it asked Capa for data in the last 30 days. Use it " +
+      "to find out what a site actually renders before changing content, and pass `entry` to " +
+      "answer \"what breaks if I unpublish this entry\". Reads the /api/ surface and needs a " +
+      "key holding the `instance:read` scope (a cap_ key with Read, or any legacy key). It " +
+      "returns no page bodies and no content, only the map.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        entry: {
+          type: "string",
+          description:
+            "An entry id (UUID). Narrows the list to the pages that read that entry in the " +
+            "last 7 days, each carrying an extra entryReads count. Omit for every page.",
+        },
+      },
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      // Refused here rather than sent: the route reads an unrecognised id as
+      // "no pages" and answers an empty list, so a typo would come back looking
+      // exactly like a correct id nothing reads. Same reasoning as
+      // capa_get_content's UUID check, and it costs zero requests.
+      const entry = args.entry === undefined || args.entry === null ? undefined : String(args.entry);
+      if (entry !== undefined && !UUID_RE.test(entry)) {
+        return {
+          error: `"${args.entry}" is not a Capa entry id.`,
+          hint:
+            "Entry ids are UUIDs, the `id` capa_list_content returns. This route answers an " +
+            "empty list for an id it does not recognise rather than an error, so a malformed " +
+            "id would look like a real entry that no page reads. Omit `entry` to list every page.",
+          pages: [],
+          total: 0,
+        };
+      }
+
+      let data;
+      let meta;
+      try {
+        ({ data, meta } = await apiNextGet(config, "/api/pages", { entry }));
+      } catch (error) {
+        if (pagesOff(error)) return PAGES_OFF;
+        throw error;
+      }
+      const rows = Array.isArray(data) ? data : [];
+      const pages = rows.map((p) => {
+        // `pattern` is dropped: the docs are explicit that it equals `id`,
+        // because the string IS the identity. Two keys holding one value is
+        // tokens an agent has to read twice to learn nothing.
+        const row = {
+          id: p.id,
+          kind: p.kind,
+          models: (p.models ?? []).map((m) => ({
+            id: m.id,
+            namespace: m.namespace,
+            // `name` rather than `modelName`, matching capa_get_model's output,
+            // so the one word means the same thing in every tool here.
+            name: m.modelName ?? m.name ?? null,
+          })),
+          reads30d: p.reads30d,
+          lastReadAt: p.lastReadAt ?? null,
+          slugField: p.slugField ?? null,
+        };
+        // Present only on an entry-filtered list, and a SHORTER window than
+        // reads30d beside it (7 days, because entry ids live only on the raw
+        // read rows). Passed through under its own key for that reason.
+        if (p.entryReads !== undefined) row.entryReads = p.entryReads;
+        return row;
+      });
+
+      const out = {
+        pages,
+        total: pages.length,
+        // Tenant-wide rows the API computed, passed through untouched. An
+        // empty array is the honest answer both when the project has no unused
+        // entries and when this deployment does not compute them yet, which is
+        // why capa_suggest_queries says which of the two it saw.
+        insights: Array.isArray(meta?.insights) ? meta.insights : [],
+      };
+      // The list is capped rather than paged. Saying so only when it bit keeps
+      // the common answer small and stops `total` being read as "all of them"
+      // when it is not.
+      if (meta?.truncated === true) out.truncated = true;
+      if (pages.length === 0) {
+        out.hint =
+          entry === undefined
+            ? "A page exists once a model declares it as a route in the Capa admin, or once a " +
+              "read arrives carrying the page as the Capa-Page header, so a project with " +
+              "neither set up yet has no pages to list."
+            : "No page read that entry in the last 7 days. Entry ids are only on the raw read " +
+              "rows and those are kept for a week, so this window is shorter than reads30d. " +
+              "A page exists once a model declares it as a route or a read arrives carrying " +
+              "the Capa-Page header, and an entry read by nothing answers the same empty list " +
+              "as an id that never existed.";
+      }
+      return out;
+    },
+  },
+
+  {
+    name: "capa_get_page",
+    ...reads("Get one page"),
+    cutHint: "capa_suggest_queries lists the page's queries on their own.",
+    surface: "api",
+    scope: "instance:read",
+    feature: "pages",
+    description:
+      "One page in full: the models it reads, the entries it showed in the last 7 days, the " +
+      "exact queries it issued (each with the select text and, where the API parsed it, the " +
+      "parsed selection), its reads per day, and any suggestions the API computed about it. " +
+      "This is how you find out how a page fetches its data before you change the code that " +
+      "renders it. Reads the /api/ surface and needs a key holding the `instance:read` scope " +
+      "(a cap_ key with Read, or any legacy key). Pass the page exactly as capa_list_pages " +
+      "returned it. It returns the page's traffic and query shapes, never the rendered page " +
+      "and never the content itself: read an entry with capa_graphql_build (mode single).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        page: {
+          type: "string",
+          description:
+            "The page path, e.g. \"/pricing\" or \"/blog/[slug]\". The concrete path a site " +
+            "served (\"/blog/hello\") is accepted too. From capa_list_pages.",
+        },
+      },
+      required: ["page"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const page = String(args.page ?? "").trim();
+      if (!page) {
+        return {
+          error: "page is required and must be non-empty.",
+          hint:
+            "A page is a path starting with \"/\", e.g. \"/pricing\" or \"/blog/[slug]\". " +
+            "capa_list_pages returns the ones this project has, and its `id` is what goes here.",
+        };
+      }
+      try {
+        // Encoded ONCE. The identity contains slashes and travels as a single
+        // path segment; the route decodes it back before it looks anything up,
+        // so encoding it twice would search for a page whose name contains
+        // "%2F".
+        const { data } = await apiNextGet(config, `/api/pages/${encodeURIComponent(page)}`);
+        // Verbatim. Fields the API adds later (the parsed selection on each
+        // query, the suggestions) reach an agent the day they ship without this
+        // tool being edited, and a field this tool does not understand is not a
+        // field it should be dropping.
+        return data;
+      } catch (error) {
+        if (pagesOff(error)) return PAGES_OFF;
+        if (error instanceof CapaApiError && error.status === 404) {
+          // In band, with the way out, following capa_get_model's didYouMean:
+          // a bare not-found makes an agent guess a second path, and the page
+          // list is the answer it would have to go and fetch anyway.
+          const available = await firstPageIds(config);
+          return {
+            error: "page_not_found",
+            hint:
+              error.hint ??
+              "A page exists once a model declares it as a route in the Capa admin, or once a " +
+                "read arrives carrying it as the Capa-Page header. capa_list_pages lists the " +
+                "ones this project has.",
+            // Omitted, not empty, when the list call failed too: `[]` would be
+            // a claim that this project has no pages, which is a different
+            // fact from "the second call did not answer either".
+            ...(available === null ? {} : { available }),
+          };
+        }
+        throw error;
+      }
+    },
+  },
+
+  {
+    name: "capa_suggest_queries",
+    ...reads("Suggest query changes for a page"),
+    cutHint: "capa_get_page has the page's models, entries and traffic.",
+    surface: "api",
+    scope: "instance:read",
+    feature: "pages",
+    description:
+      "What Capa suggests changing about how one page fetches its data, plus the queries the " +
+      "page actually issued. The suggestions are computed by the API from that page's own " +
+      "reads, so this tool reports them rather than deriving anything itself, and the Capa " +
+      "admin shows the same ones. Use it after capa_get_page when you are about to rewrite a " +
+      "page's data fetching. Reads the /api/ surface and needs a key holding the " +
+      "`instance:read` scope (a cap_ key with Read, or any legacy key). An empty list is an " +
+      "answer, not a failure, and `note` says which kind of empty it is.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        page: {
+          type: "string",
+          description: "The page path, exactly as capa_list_pages returned it.",
+        },
+      },
+      required: ["page"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const page = String(args.page ?? "").trim();
+      if (!page) {
+        return {
+          error: "page is required and must be non-empty.",
+          hint:
+            "A page is a path starting with \"/\", e.g. \"/pricing\". capa_list_pages returns " +
+            "the ones this project has.",
+        };
+      }
+      let detail;
+      try {
+        const res = await apiNextGet(config, `/api/pages/${encodeURIComponent(page)}`);
+        detail = res.data;
+      } catch (error) {
+        if (pagesOff(error)) return PAGES_OFF;
+        if (error instanceof CapaApiError && error.status === 404) {
+          return {
+            error: "page_not_found",
+            hint:
+              error.hint ??
+              "A page exists once a model declares it as a route in the Capa admin, or once a " +
+                "read arrives carrying it as the Capa-Page header. capa_list_pages lists the " +
+                "ones this project has.",
+          };
+        }
+        throw error;
+      }
+
+      const insights = Array.isArray(detail?.insights) ? detail.insights : [];
+      // One row per distinct (model, select) the page asked for, which is how a
+      // page fetching far more than it renders shows up. Trimmed to the three
+      // fields that answer "what did it ask for and how often": the detail
+      // carries the key ids and timestamps beside them, and capa_get_page is
+      // where to read those.
+      const queries = (detail?.queries ?? []).map((q) => ({
+        modelNamespace: q.namespace ?? null,
+        selectText: q.selectText ?? null,
+        reads: q.reads,
+      }));
+
+      const out = { page: detail?.page ?? page, insights, queries };
+      if (insights.length === 0) {
+        out.note =
+          queries.length === 0
+            ? "No suggestions: this page issued no reads in the window Capa measures, so there " +
+              "is nothing to suggest about. A page's queries appear here once its reads arrive " +
+              "carrying the page as the Capa-Page header."
+            : "No suggestions: the API computes them from this page's own reads and returned " +
+              "none, which means either every query is already narrow or this deployment does " +
+              "not compute them yet. The queries listed are what the page actually issued, " +
+              "verbatim, so you can judge them yourself.";
+      }
+      return out;
+    },
+  },
+
+  // ------------------------------------------- GraphQL and data (/api/) ---
+  //
+  // Finding, writing, running and reading queries: lib/graphql-tools.mjs.
+  ...GRAPHQL_TOOLS,
+
+  // ------------------------------------------ REST, where GraphQL is off ---
+  //
+  // Reading entries when the deployment serves no GraphQL: lib/rest-tools.mjs.
+  ...REST_TOOLS,
+];
+
+/**
+ * A page route answering `route_not_found` is a deployment without pages
+ * (`CAPA_SITE_PREVIEW` off), not a page that does not exist. The server
+ * leaves these tools out when it can tell at startup; this is the answer when
+ * it could not.
+ */
+const pagesOff = (error) => error instanceof CapaApiError && error.status === 404 && error.code === "route_not_found";
+const PAGES_OFF = {
+  error: "pages_not_enabled",
+  hint:
+    "This deployment does not serve pages (CAPA_SITE_PREVIEW is off), so no page can be listed or read here. " +
+    "To see what content a model holds, use capa_graphql_schema and capa_explore_data.",
+};
+
+/**
+ * The first page ids this project has, for the `available` list on a 404.
+ *
+ * Null rather than `[]` when the call fails: an empty array is a claim that
+ * the project has no pages, and the tool has not learned that.
+ */
+async function firstPageIds(config) {
+  try {
+    const { data } = await apiNextGet(config, "/api/pages");
+    return (Array.isArray(data) ? data : []).slice(0, 20).map((p) => p.id);
+  } catch {
+    return null;
+  }
+}
+
+export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));