@nestr/mcp 0.1.104 → 0.1.106

package/build/tools/index.js

@@ -356,6 +356,7 @@ const HINT_ENDPOINT_TOOL_MAPPINGS = [
         bodyParams: new Set([
             "_id", "title", "labels", "description", "purpose",
             "parentId", "users", "due", "accountabilities", "domains",
+            "role", // operational output: the role the work is asked of
             "roleId", // election mode
         ]),
     },
@@ -369,6 +370,7 @@ const HINT_ENDPOINT_TOOL_MAPPINGS = [
         bodyParams: new Set([
             "_id", "title", "labels", "description", "purpose",
             "parentId", "users", "due", "accountabilities", "domains",
+            "role",
         ]),
     },
     // DELETE /parts (body has _id) — propose deletion of an existing item.
@@ -490,6 +492,93 @@ export function nestrWebBase(apiBase) {
     return base.replace(/\/api\/?$/, "").replace(/\/+$/, "") || "https://app.nestr.io";
 }
 const NESTR_WEB_BASE = nestrWebBase(process.env.NESTR_API_BASE);
+/**
+ * Turn the tool-level `hints` argument into what the API should be sent.
+ *
+ * `false` means none. A level passes through. `undefined` and `true` both take the
+ * caller-appropriate default, which differs by call shape on purpose: a single read
+ * wants the teaching prose, a listing wants it once from nestr_help rather than once
+ * per row.
+ */
+export function resolveHintLevel(value, fallback) {
+    if (value === false)
+        return false;
+    if (value === "full" || value === "summary")
+        return value;
+    return fallback;
+}
+/**
+ * Append `strict:true` unless the caller already asked for it.
+ *
+ * Without it an unrecognised operator, label or field filter is silently dropped and the
+ * search returns a broader result that looks like a real answer. That is fine for
+ * browsing and wrong for counting, so the tool exposes it as a flag rather than making
+ * every caller remember the operator.
+ */
+export function withStrict(query, strict) {
+    if (!strict)
+        return query;
+    if (/(^|\s)strict:true(\s|$)/i.test(query))
+        return query;
+    return `${query} strict:true`;
+}
+/**
+ * Reduce an OpenAPI document to something a model can read.
+ *
+ * The whole document is far too large to return, and returning nothing useful is how a
+ * caller ends up guessing whether an endpoint exists. So: an operation index by default,
+ * one operation in full when asked for by path, and a keyword filter in between. The
+ * counts matter as much as the rows — "0 of 94 operations match 'duration'" is the
+ * answer to "does the API store meeting duration", and it is a real negative rather than
+ * a failed search.
+ */
+export function summariseApiSpec(spec, filter = {}) {
+    const paths = (spec?.paths || {});
+    const allPaths = Object.keys(paths);
+    if (filter.path) {
+        const match = allPaths.find((p) => { return p === filter.path; })
+            || allPaths.find((p) => { return p.toLowerCase() === filter.path.toLowerCase(); });
+        if (!match) {
+            return {
+                found: false,
+                requested: filter.path,
+                totalPaths: allPaths.length,
+                note: "No such path in this deployment's spec. This is a definitive negative, not a failed lookup.",
+                // Intentionally broad rather than precise: the first path segment, so
+                // `/nests/{id}/nonsense` suggests everything under `/nests/`. A caller who got the
+                // path wrong usually has the resource right, and a wide list they can scan beats a
+                // narrow one that misses the route they meant. Capped so it stays readable.
+                didYouMean: allPaths.filter((p) => { return p.includes(filter.path.split("/")[1] || ""); }).slice(0, 10),
+            };
+        }
+        return { found: true, path: match, operations: paths[match] };
+    }
+    const rows = [];
+    for (const p of allPaths) {
+        for (const [method, op] of Object.entries(paths[p] || {})) {
+            if (typeof op !== "object" || op === null)
+                continue;
+            const summary = (op.summary || op.description || "").split("\n")[0].slice(0, 160);
+            rows.push({ method: method.toUpperCase(), path: p, summary });
+        }
+    }
+    const needle = filter.search?.toLowerCase();
+    const matched = needle
+        ? rows.filter((r) => {
+            return r.path.toLowerCase().includes(needle) || r.summary.toLowerCase().includes(needle);
+        })
+        : rows;
+    return {
+        totalOperations: rows.length,
+        matchedOperations: matched.length,
+        ...(needle ? { query: filter.search } : {}),
+        ...(needle && matched.length === 0
+            ? { note: `No operation mentions "${filter.search}". This deployment does not serve one, which is a definitive answer rather than a failed search.` }
+            : {}),
+        operations: matched.slice(0, 200),
+        ...(matched.length > 200 ? { truncated: true } : {}),
+    };
+}
 export function enrichHints(data) {
     if (!data || typeof data !== "object")
         return data;
@@ -563,9 +652,78 @@ export function enrichHints(data) {
     // `data` would discard both the enriched payload and the enriched envelope hints.
     return subject;
 }
-function buildNestUrl(id, parentId) {
+// Which of the PARENT's tabs holds a child carrying this label, keyed by the
+// API-facing label name (the API strips `circleplus-` and renames
+// prepared-tension to tension, so these are the names that actually arrive).
+//
+// This is the reverse of the `labels: [...]` declarations the tab definitions
+// already carry in slashme-online `packages/nestr_circleplus/lib/tabs.js`: the
+// Projects tab declares it holds project / individual-action / sprint / epic,
+// the Roles tab declares role / circle, and so on. A few tabs (Goals, Todos,
+// Metrics on a circle) express the same containment as a `searchTerm` rather
+// than a labels array, so those entries are read off the search and written
+// here by hand.
+//
+// Why a static map rather than asking the server which tab contains this nest:
+// the precise answer needs the PARENT's resolved tab set, and getTabs() on the
+// server evaluates the circleplus tab callback (a walk through getWorkspace,
+// getData and TAPi18n). translateNest runs per row on every search and children
+// response, so that is a per-row cost on the hot path for a link most rows never
+// need. A wrong guess costs nothing: listview_lists falls back to the nest's
+// default tab when the hash names no available tab, which is exactly the
+// hashless behaviour we have today.
+const LABEL_CONTAINING_TAB = {
+    project: "projects",
+    "individual-action": "projects",
+    sprint: "projects",
+    epic: "projects",
+    task: "tasks",
+    role: "roles",
+    circle: "roles",
+    "anchor-circle": "roles",
+    domain: "policies",
+    policy: "policies",
+    meeting: "meetings",
+    governance: "meetings",
+    tactical: "meetings",
+    tension: "meetings",
+    metric: "metrics",
+    checklist: "checklists",
+    goal: "goals",
+    result: "goals",
+    skill: "skills",
+    feedback: "feedback",
+    note: "notes",
+};
+// The tab on the parent that a person opens to SEE this nest in its list.
+// First label wins, so a scrum story labelled ["project", "userstory"] resolves
+// through `project` and lands on Projects.
+export function containingTabHash(labels) {
+    if (!Array.isArray(labels))
+        return undefined;
+    for (const label of labels) {
+        if (typeof label !== "string")
+            continue;
+        const tab = LABEL_CONTAINING_TAB[label];
+        if (tab)
+            return tab;
+    }
+    return undefined;
+}
+// A nest URL without a `#` is NOT a stable link. listview_lists reads the tab
+// from localStorage `<nestId>_preferred_header`, so the same link opens whichever
+// tab that particular person last used on that particular nest, and a first-time
+// visitor gets the container's first tab — which for a circle is Structure >
+// About, not the work they were sent to look at. Carrying the hash is what makes
+// the link mean the same thing to everyone.
+//
+// The hash belongs to the LEFT pane, which in the two-id form is the parent, so
+// it is only appended there. On the bare `/n/{id}` form the hash would select a
+// tab on the nest ITSELF, and `#projects` on a project means nothing.
+function buildNestUrl(id, parentId, labels) {
     if (parentId && parentId.toLowerCase() !== "inbox") {
-        return `${NESTR_WEB_BASE}/n/${parentId}/${id}`;
+        const tab = containingTabHash(labels);
+        return `${NESTR_WEB_BASE}/n/${parentId}/${id}${tab ? `#${tab}` : ""}`;
     }
     return `${NESTR_WEB_BASE}/n/${id}`;
 }
@@ -597,7 +755,7 @@ export function addNestUrls(data) {
     const record = data;
     const out = { ...record };
     if (looksLikeNest(record) && typeof out.url !== "string") {
-        out.url = buildNestUrl(record._id, record.parentId);
+        out.url = buildNestUrl(record._id, record.parentId, record.labels);
     }
     for (const [key, value] of Object.entries(out)) {
         if (value && typeof value === "object") {
@@ -652,9 +810,27 @@ const MENTION_DESC = "Supports HTML and @mentions. Mentions MUST use literal cur
 const PRIME_LABEL_RULE = "At most ONE prime label per nest (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback, userstory, sprint, epic, milestone): they are the nest's identity and cannot coexist. Only exception: userstory may pair with project.";
 const PURPOSE_DESC = "Only for workspaces, circles and roles: a short aspirational statement. Details belong in description, not here. Supports HTML.";
 const CONTENT_DESC = "The primary content field: details, context, acceptance criteria. Structured data goes in fields, progress in comments. Supports Markdown and HTML.";
+const HINTS_DESC = "Contextual hints. 'summary' keeps the per-nest signal (type, severity, count, url, and the "
+    + "`query` that finds every other nest with the same problem) and drops the fixed teaching prose "
+    + "and endpoint list. 'full' is the whole payload. false for none.";
 const STRIP_DESCRIPTION = "Strip description fields to shrink the response. Use for bulk or index reads.";
 const SORT_DESCRIPTION = "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only).";
 // Tool input schemas using Zod
+/**
+ * `hints` is a level, not a flag. `summary` keeps what varies per nest and drops the
+ * teaching prose and endpoint list, which are identical for every nest of a type; `full`
+ * is the whole payload. Booleans still work: the API reads a bare `true` on a listing as
+ * `summary`, which is the difference between one paragraph and fifty copies of it.
+ */
+const hintLevelSchema = z.union([z.boolean(), z.enum(["full", "summary"])]).optional();
+const hintFilterSchemas = {
+    hintTypes: coerceFromJson(z.array(z.string())).optional()
+        .describe("Keep only these hint types, e.g. ['project_waiting_no_reason','unassigned_role']."),
+    minSeverity: z.enum(["info", "suggestion", "warning", "alert"]).optional()
+        .describe("Drop hints below this severity. 'warning' is the useful floor when sweeping."),
+};
+const linkedUsersSchema = z.boolean().optional()
+    .describe("Resolve every user id in the results to a full user, returned once in linked.users.");
 export const schemas = {
     listWorkspaces: z.object({
         search: z.string().optional().describe("Search query to filter workspaces"),
@@ -719,6 +895,8 @@ export const schemas = {
     search: z.object({
         workspaceId: z.string().describe("Workspace ID to search in"),
         query: z.string().describe("Search query"),
+        strict: z.boolean().optional().describe("Reject the search if any operator, label or field filter in it was not recognised, instead of silently returning a broader result. Use it whenever you are counting rather than browsing: without it a typo'd filter reads as a real, larger answer."),
+        linkedUsers: linkedUsersSchema,
         sort: z.string().optional().describe(`${SORT_DESCRIPTION} Takes precedence over sort:/sort-order: operators in the query.`),
         limit: z.number().optional().describe("Max results per page. Omit on first call to see meta.total count."),
         page: z.number().optional().describe("Page number (1-indexed) for pagination"),
@@ -727,7 +905,8 @@ export const schemas = {
     getNest: z.object({
         nestId: z.string().describe("Nest ID. Supports comma-separated IDs to fetch multiple nests in one call (e.g., 'id1,id2,id3') — returns an array instead of a single object. Keep total URL under 2000 chars to avoid HTTP limits."),
         fieldsMetaData: z.boolean().optional().describe("Set to true to include field schema metadata (e.g., available options for project.status)"),
-        hints: z.boolean().optional().describe("Include contextual hints on each nest (default: true). Hints surface actionable signals like unassigned roles, stale projects, or unread comments. Set to false for bulk lookups where you only need structural data, not contextual guidance."),
+        hints: hintLevelSchema.describe("Contextual hints: 'full' (default on a single read), 'summary', or false. 'summary' keeps type, severity, count, url and the sibling query, and drops the teaching prose and endpoints. Hints surface signals like unassigned roles, stale projects or unread comments."),
+        ...hintFilterSchemas,
         provenance: z.boolean().optional().describe("Single-nest only. Include field/property provenance: which label (and circle context) defines each field and property."),
         rights: z.boolean().optional().describe("Single-nest only. Include the caller's composed rights on the nest plus a deny trace naming the profiles that block each op."),
         forUser: z.string().optional().describe("Single nest, with rights=true. Rights for this user id instead of the caller. Caller must be a nest admin."),
@@ -740,12 +919,25 @@ export const schemas = {
     }),
     getNestChildren: z.object({
         nestId: z.string().describe("Parent nest ID"),
+        search: z.string().optional().describe("Search scoped to this nest, full operator syntax. Ask for the subset you want rather than fetching every child and filtering: 'label:role' for a circle's roles, 'label:project fields.project.status:Waiting' for its waiting projects. depth:1 is applied when you set no depth, and the response says so in appliedDefaults."),
         sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
-        hints: z.boolean().optional().describe("Include contextual hints on each child nest (default: true). Set to false for large result sets or bulk operations where contextual signals aren't needed."),
+        hints: hintLevelSchema.describe("Contextual hints: 'summary' (default on a listing), 'full', or false. A listing at 'full' repeats the same teaching prose once per row."),
+        ...hintFilterSchemas,
+        linkedUsers: linkedUsersSchema,
         _listTitle: z.string().optional().describe("Short descriptive title for the list UI (e.g., \"Tasks for Website Redesign\"). Omit for default."),
     }),
+    hintsRollup: z.object({
+        nestId: z.string().describe("Nest to roll up. A circle or workspace root is the useful scope."),
+        hintTypes: coerceFromJson(z.array(z.string())).optional().describe("Count only these hint types."),
+        minSeverity: z.enum(["info", "suggestion", "warning", "alert"]).optional().describe("Drop rules below this severity."),
+        sampleSize: z.number().optional().describe("Example nests per type. Default 10, max 100, 0 for counts only."),
+    }),
+    apiSpec: z.object({
+        search: z.string().optional().describe("Filter operations by keyword against path and summary, e.g. 'meeting' or 'tension'."),
+        path: z.string().optional().describe("Return the full schema for one path, e.g. '/nests/{id}/children'."),
+    }),
     createNest: z.object({
         parentId: z.string().describe("Parent nest ID (workspace, circle, or project)"),
         title: z.string().describe("Title of the new nest (plain text, HTML stripped)"),
@@ -809,6 +1001,7 @@ export const schemas = {
         sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
+        linkedUsers: linkedUsersSchema,
     }),
     listUserRoles: z.object({
         userId: z.string().optional().describe("User ID to look up. Omit for yourself. Requires workspaceId when set."),
@@ -843,6 +1036,7 @@ export const schemas = {
         sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
+        linkedUsers: linkedUsersSchema,
         _listTitle: z.string().optional().describe("Short descriptive title for the list UI (e.g., \"Engineering projects\"). Omit for default."),
     }),
     getComments: z.object({
@@ -987,7 +1181,6 @@ export const schemas = {
         sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results to return"),
         page: z.number().optional().describe("Page number for pagination"),
-        order: z.string().optional().describe("Deprecated alias of sort"),
     }),
     updateTension: z.object({
         nestId: z.string().describe("ID of the circle or role the tension belongs to"),
@@ -1018,6 +1211,7 @@ export const schemas = {
         due: z.string().optional().describe("Due or re-election date, ISO. For an election, the term end; omit for no term."),
         accountabilities: coerceFromJson(z.array(z.string())).optional().describe("Accountability titles on a role (replaces all; children tools for individual edits)"),
         domains: coerceFromJson(z.array(z.string())).optional().describe("Domain titles on a role (replaces all; children tools for individual edits)"),
+        role: z.string().optional().describe("The role this output belongs to, for an operational output (pathway 3/4). Pair with users: users is WHO does it, role is the role it is asked of, and the work request names both (\"Ada as Systems: ...\"). A role id, not a title. Distinct from roleId, which is election mode."),
         roleId: z.string().optional().describe("Hold an ELECTION: the electable role to fill (Facilitator/Secretary/Rep Link or any electable role). Assigns or reconfirms the role's filler for a term WITHOUT changing its accountabilities/domains — provide users:[userId] (one person) and optional due (term). Do not combine with _id."),
         removeNest: z.boolean().optional().describe("Set true with _id to propose deletion of the referenced governance item (when the proposal is accepted, the item is removed). Distinct from nestr_remove_tension_part, which undoes a proposal part you already added. Requires _id; other body fields are ignored."),
     }).refine((data) => !data.removeNest || !!data._id, { message: "removeNest:true requires _id to identify which item to propose for deletion" }).refine((data) => !data.roleId || (Array.isArray(data.users) && data.users.length === 1), { message: "An election (roleId) requires exactly one user to elect — users: [userId]." }).refine((data) => !(data.roleId && data._id), { message: "Provide either roleId (to hold an election) or _id (to change/delete an existing item), not both." }),
@@ -1034,6 +1228,7 @@ export const schemas = {
         due: z.string().optional().describe("Updated due date (ISO format)"),
         accountabilities: coerceFromJson(z.array(z.string())).optional().describe("Updated accountabilities (replaces all; children tools for individual edits)"),
         domains: coerceFromJson(z.array(z.string())).optional().describe("Updated domains (replaces all; children tools for individual edits)"),
+        role: z.string().optional().describe("Updated role for an operational output. A role id; pass an empty string to clear it."),
     }),
     removeTensionPart: z.object({
         nestId: z.string().describe("ID of the circle or role the tension belongs to"),
@@ -1206,7 +1401,7 @@ const destructive = { annotations: { readOnlyHint: false, destructiveHint: true
 export const toolDefinitions = [
     {
         name: "nestr_help",
-        description: "Nestr documentation, three modes. (1) Internal topic: `topic` with a curated key (search, labels, nest-model, inbox, daily-plan, notifications, insights, tension-processing, skills, mcp-apps, authentication, scrum, okr, ...); 'topics' lists them all. (2) Help article: `topic` with a slug from nestr.io/help/articles/<slug>; returns markdown plus a numbered list of its images. Images are never attached by default: includeImages:true takes the first maxImages screenshots, imageIndexes:[..] takes chosen ones. Attach when the user wants to see how something looks. (3) Search: `search` with free text; returns ranked matches, each a title and one-line summary, tolerant of typos and synonyms (kanban/sprint to scrum). A topic is tried internally first, then as an article. Every response opens with 'Resolved as:' naming the mode, and topics and articles cross-link. Call before unfamiliar operations. No auth.",
+        description: "Nestr documentation, three modes. (1) Internal topic: `topic` with a curated key (search, labels, nest-model, inbox, daily-plan, notifications, insights, tension-processing, skills, mcp-apps, authentication, scrum, okr, ...); 'topics' lists them all. (2) Help article: `topic` with a slug from nestr.io/help/articles/<slug>; returns markdown plus a numbered list of its images. Images are never attached by default: includeImages:true takes the first maxImages screenshots, imageIndexes:[..] takes chosen ones. Attach when the user wants to see how something looks. (3) Search: `search` with free text, **in English whatever language the conversation is in** — the corpus is English and the index scores slugs and keywords, so a query in another language usually returns nothing; returns ranked matches, each a title and one-line summary, tolerant of typos and synonyms (kanban/sprint to scrum). A topic is tried internally first, then as an article. Every response opens with 'Resolved as:' naming the mode, and topics and articles cross-link. Call before unfamiliar operations. No auth.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1296,12 +1491,14 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_search",
-        description: "Search nests in a workspace. Supports operators like label:, assignee:, createdby:, completed:, in:, sort:. createdby: accepts me, an email address, or a user id. Always use completed:false for active work. See nestr_help('search') for full syntax. Results carry user ids; when presenting to a person, show names and/or emails, resolving ids via nestr_get_user or nestr_list_users.",
+        description: "Search nests in a workspace. Supports operators like label:, assignee:, createdby:, completed:, in:, sort:. createdby: accepts me, an email address, or a user id. Always use completed:false for active work. See nestr_help('search') for full syntax. Results carry user ids; when presenting to a person, show names and/or emails. Pass `linkedUsers: true` to get them all resolved in the same request rather than calling nestr_get_user per id.",
         inputSchema: {
             type: "object",
             properties: {
                 workspaceId: { type: "string", description: "Workspace ID to search in" },
                 query: { type: "string", description: "Search query with optional operators (e.g., 'label:role', 'assignee:me completed:false')" },
+                strict: { type: "boolean", description: "Reject the search when any operator, label or field filter in it was not recognised, rather than silently returning a broader result. Use it whenever you are counting rather than browsing: without it, a mistyped filter comes back as a real and larger answer with nothing to say the filter was dropped." },
+                linkedUsers: { type: "boolean", description: "Resolve every user id in the results to a full user, returned once in `linked.users`. Prefer this over calling nestr_get_user per id." },
                 sort: { type: "string", description: `${SORT_DESCRIPTION} Takes precedence over sort:/sort-order: operators in the query.` },
                 limit: { type: "number", description: "Max results per page. Omit on the first call so meta.total shows the match count." },
                 page: { type: "number", description: "Page number (1-indexed) for fetching additional pages" },
@@ -1322,7 +1519,9 @@ export const toolDefinitions = [
             properties: {
                 nestId: { type: "string", description: "Nest ID, or comma-separated IDs for a batch (e.g. 'id1,id2'). Keep the URL under 2000 chars." },
                 fieldsMetaData: { type: "boolean", description: "Set to true to include field schema metadata (available options, field types)" },
-                hints: { type: "boolean", description: "Contextual hints, default true. False for bulk lookups needing only structure." },
+                hints: { type: ["string", "boolean"], enum: ["summary", "full", true, false], description: `${HINTS_DESC} Defaults to 'full' on a single read, which is what you want when you asked about one nest.` },
+                hintTypes: { type: "array", items: { type: "string" }, description: "Keep only these hint types." },
+                minSeverity: { type: "string", enum: ["info", "suggestion", "warning", "alert"], description: "Drop hints below this severity." },
                 stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
                 provenance: { type: "boolean", description: "Single nest. Which label and circle context defines each field and property, e.g. why a role has a given icon." },
                 rights: { type: "boolean", description: "Single nest. The caller's composed rights (self read/update/delete) plus a deny trace naming what blocks each op, and why." },
@@ -1349,15 +1548,19 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_get_nest_children",
-        description: "Get children of a nest. Paginated. Add hints=true for contextual signals.",
+        description: "Get children of a nest, or just the ones you want. Pass `search` with the full operator syntax to ask for a subset rather than fetching everything and filtering: `search: 'label:role'` returns a circle's roles in one call. Paginated at 50 per page; read meta.total for the match count.",
         inputSchema: {
             type: "object",
             properties: {
                 nestId: { type: "string", description: "Parent nest ID" },
+                search: { type: "string", description: "Search scoped to this nest, full operator syntax. Ask for the subset you want instead of fetching every child and filtering: `label:role` for a circle's roles, `label:project fields.project.status:Waiting` for its waiting projects. `depth:1` is applied when you set no depth and the response says so in `appliedDefaults`; pass `depth:2` or higher to reach further down." },
                 sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
-                hints: { type: "boolean", description: "Include contextual hints (default: true). Set to false for large result sets or bulk operations." },
+                hints: { type: ["string", "boolean"], enum: ["summary", "full", true, false], description: `${HINTS_DESC} Defaults to 'summary' here: a listing at 'full' repeats the same paragraph once per row.` },
+                hintTypes: { type: "array", items: { type: "string" }, description: "Keep only these hint types." },
+                minSeverity: { type: "string", enum: ["info", "suggestion", "warning", "alert"], description: "Drop hints below this severity." },
+                linkedUsers: { type: "boolean", description: "Resolve every user id in the results to a full user, returned once in `linked.users`. One request instead of one per id." },
                 stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
                 _listTitle: { type: "string", description: "Short descriptive title for the list UI header (e.g., \"Tasks for Website Redesign\", \"API project sub-tasks\"). Include the parent name for context." },
             },
@@ -1367,9 +1570,36 @@ export const toolDefinitions = [
         // The completable list app should only be used when results are confirmed to be completable items.
         ...readOnly,
     },
+    {
+        name: "nestr_hints_rollup",
+        description: "Count hints across a whole circle or workspace in one call. A hint on a single nest says \"this one has this problem\"; this says how many have it, which is the question you actually ask of a circle. Answers \"how healthy is this circle\", \"how many projects are waiting with no reason\", \"how many roles have nobody in them\" without reading every nest. Each result carries type, severity, count and a small sample to open. Read `notComputed`: it names every hint type this cannot count in one query, so a type listed there is unknown rather than zero. Do not sum counts across types, one nest can carry several; ask for a single hintTypes when you want a number that adds up.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "Nest to roll up. A circle or the workspace root is the useful scope." },
+                hintTypes: { type: "array", items: { type: "string" }, description: "Count only these hint types. Omit for every type this can compute." },
+                minSeverity: { type: "string", enum: ["info", "suggestion", "warning", "alert"], description: "Drop rules below this severity. 'warning' is the useful floor for \"what needs attention\"." },
+                sampleSize: { type: "number", description: "Example nests per type. Default 10, max 100, 0 for counts only." },
+            },
+            required: ["nestId"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_api_spec",
+        description: "The deployment's own OpenAPI document, so you can check whether the API has something rather than concluding \"I did not find it\" and guessing. Call with no arguments for the operation index (method, path, one-line summary). `search` filters by keyword against path and summary. `path` returns the full schema for one operation, including its parameters. Use this to answer \"is there an endpoint for X\" with certainty, and note that a negative here is a real negative: if it is not in the spec, this deployment does not serve it. For the search query language rather than the HTTP surface, use nestr_help('search'); for a filter you are unsure of, `strict: true` on nestr_search tells you whether it applied.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                search: { type: "string", description: "Filter operations by keyword against path and summary, e.g. 'meeting', 'tension', 'duration'." },
+                path: { type: "string", description: "Return the full schema for one path, e.g. '/nests/{id}/children'." },
+            },
+        },
+        ...readOnly,
+    },
     {
         name: "nestr_create_nest",
-        description: `Create a nest under a parent. Labels define the type, e.g. ['project'], ['role']. ${PRIME_LABEL_RULE} Sprint/epic/milestone never pair; stories link to those via graph relations. In established workspaces prefer the tension flow for governance. See nestr_help('labels').`,
+        description: `Create a nest under a parent. Labels define the type, e.g. ['project'], ['role']. ${PRIME_LABEL_RULE} Sprint/epic/milestone never pair; stories link to those via graph relations. In established workspaces prefer the tension flow for governance. Meetings attach to a circle that ALREADY exists — the workspace anchor circle counts, and is the right parent when no sub-circle fits. Never create a circle to hold a meeting. Use \`['meeting','circle-meeting']\` for a tactical meeting, \`['meeting','governance']\` for a governance meeting, and set \`due\` to the start time. See nestr_help('labels') and nestr_help('meetings').`,
         inputSchema: {
             type: "object",
             properties: {
@@ -1586,6 +1816,7 @@ export const toolDefinitions = [
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
                 stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
+                linkedUsers: { type: "boolean", description: "Resolve every user id in the results to a full user, returned once in `linked.users`. One request instead of one per id." },
             },
             required: ["workspaceId"],
         },
@@ -1801,6 +2032,7 @@ export const toolDefinitions = [
                 page: { type: "number", description: "Page number (1-indexed)" },
                 stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
                 _listTitle: { type: "string", description: "Short descriptive title for the list UI header (e.g., \"Engineering projects\", \"All projects\"). Omit for default." },
+                linkedUsers: { type: "boolean", description: "Resolve every user id in the results to a full user, returned once in `linked.users`. One request instead of one per id." },
             },
             required: ["workspaceId"],
         },
@@ -1818,6 +2050,7 @@ export const toolDefinitions = [
                     oneOf: [{ type: "number" }, { type: "string", enum: ["all"] }],
                     description: "How deep below the context nest to look for comments. 0 (default) returns only comments directly on this nest; N includes comments on descendants up to N levels deep; 'all' includes comments on this nest and every descendant.",
                 },
+                unread: { type: "boolean", description: "true for comments you have not read, false for the ones you have. Omit for all. Combine with depth to sweep a circle for what you have missed." },
             },
             required: ["nestId"],
         },
@@ -1905,7 +2138,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_get_workspace_apps",
-        description: "List enabled apps/features in a workspace. Check before using features that require specific apps (e.g., Insights).",
+        description: "List a workspace's apps/features. Returns the FULL catalogue, each entry `{ _id, title, enabled }` — a disabled app is present with `enabled: false`, never absent, so test `enabled` and not presence. Note the field is `_id`, not `id`. Check before using features that require specific apps (e.g., Insights, Scrum, Meetings).",
         inputSchema: {
             type: "object",
             properties: {
@@ -2258,9 +2491,6 @@ export const toolDefinitions = [
                 sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Max results to return" },
                 page: { type: "number", description: "Page number (1-indexed)" },
-                // The legacy `order` alias is deliberately not advertised — the Zod
-                // schema still accepts it so existing callers keep working, but new
-                // clients should only learn the canonical `sort` param.
             },
             required: ["nestId"],
         },
@@ -2311,7 +2541,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_tension_part",
-        description: "Add a governance proposal part to a tension. Modes: new item (omit _id, give title/labels); change one (_id plus the changed fields; editing a role copies its accountabilities/domains in, so it reads as a full role edit); delete one (_id plus removeNest:true); election (roleId plus users:[userId], optional due, which assigns or reconfirms the filler and leaves accountabilities/domains untouched). See nestr_help('tension-processing').",
+        description: "Add a part to a tension. A part is either the operational work the tension asks for or a governance change it proposes. Modes: OPERATIONAL OUTPUT (title, description, users, role, and no governance label) is what a work request is made of, and is the common case; new governance item (omit _id, give title plus a governance label such as ['role'] or ['policy']); change one (_id plus the changed fields; editing a role copies its accountabilities/domains in, so it reads as a full role edit); delete one (_id plus removeNest:true); election (roleId plus users:[userId], optional due, which assigns or reconfirms the filler and leaves accountabilities/domains untouched). The part you get back has its own _id and a sourceId, the output nest underneath it; nestr_modify_tension_part takes the part _id, not the sourceId. See nestr_help('tension-processing').",
         inputSchema: {
             type: "object",
             properties: {
@@ -2327,6 +2557,7 @@ export const toolDefinitions = [
                 due: { type: "string", description: "Due or re-election date, ISO. For an election, the term end; omit for no term." },
                 accountabilities: { type: "array", items: { type: "string" }, description: "Accountability titles on a role (replaces all; children tools for individual edits)" },
                 domains: { type: "array", items: { type: "string" }, description: "Domain titles on a role (replaces all; children tools for individual edits)" },
+                role: { type: "string", description: "The role this output belongs to, for an operational output (pathway 3/4). Pair with users: users is WHO does it, role is the role it is asked of, and the work request names both (\"Ada as Systems: ...\"). A role id, not a title. Distinct from roleId, which is election mode." },
                 roleId: { type: "string", description: "ELECTION mode: the electable role to fill (Facilitator, Secretary, Rep Link or any electable role). Pair with users:[oneUserId] and optional due. Never with _id." },
                 removeNest: { type: "boolean", description: "With _id, propose deleting that governance item; it goes when the proposal is accepted. Not nestr_remove_tension_part, which undoes a part you already added." },
             },
@@ -2350,6 +2581,7 @@ export const toolDefinitions = [
                 parentId: { type: "string", description: "Updated parent ID" },
                 users: { type: "array", items: { type: "string" }, description: "Updated user assignments" },
                 due: { type: "string", description: "Updated due date (ISO format)" },
+                role: { type: "string", description: "Updated role for an operational output. A role id; pass an empty string to clear it." },
                 accountabilities: { type: "array", items: { type: "string" }, description: "Updated accountabilities (replaces all; children tools for individual edits)" },
                 domains: { type: "array", items: { type: "string" }, description: "Updated domains (replaces all; children tools for individual edits)" },
             },
@@ -2960,7 +3192,7 @@ async function _handleToolCall(client, name, args, context) {
                         const entries = await loadArticleIndex();
                         const hits = searchArticleIndex(entries, parsed.search, 8);
                         if (hits.length === 0) {
-                            return { content: [{ type: "text", text: `_Resolved as: help-article search._\n\nNo help articles matched "${parsed.search}". The index scores article slugs and curated keywords, not article bodies, so an exact feature, operator or field name often misses even when the docs cover it. Try broader terms or a synonym, or call nestr_help({ topic: "topics" }) for internal MCP topics. An empty result is not evidence the thing does not exist: say you could not find it documented, never that it is unsupported.` }] };
+                            return { content: [{ type: "text", text: `_Resolved as: help-article search._\n\nNo help articles matched "${parsed.search}". **The corpus and the index are English. If you searched in another language, translate the query and search again before concluding anything** — that is the single most common reason for an empty result, and one retry usually fixes it. Beyond that: the index scores article slugs and curated keywords, not article bodies, so an exact feature, operator or field name often misses even when the docs cover it. Try broader terms or a synonym, or call nestr_help({ topic: "topics" }) for internal MCP topics. An empty result is not evidence the thing does not exist: say you could not find it documented, never that it is unsupported. Never fill the gap from memory on anything a customer could check — prices, limits and plan names above all.` }] };
                         }
                         // Enrich the top hits with a title + one-line summary so the caller
                         // can pick the right article without a blind fetch. Best-effort:
@@ -3144,11 +3376,12 @@ async function _handleToolCall(client, name, args, context) {
             case "nestr_search": {
                 const parsed = schemas.search.parse(args);
                 const directives = extractSearchDirectives(parsed.query);
-                const results = await client.searchWorkspace(parsed.workspaceId, parsed.query, {
+                const results = await client.searchWorkspace(parsed.workspaceId, withStrict(parsed.query, parsed.strict), {
                     sort: parsed.sort ?? directives.sort,
                     limit: parsed.limit ?? directives.limit,
                     page: parsed.page,
                     cleanText: true,
+                    linkedUsers: parsed.linkedUsers,
                 });
                 return formatResult(completableResponse(compactResponse(results), "search", parsed._listTitle || `Search: ${parsed.query}`));
             }
@@ -3157,7 +3390,9 @@ async function _handleToolCall(client, name, args, context) {
                 const nest = await client.getNest(parsed.nestId, {
                     cleanText: true,
                     fieldsMetaData: parsed.fieldsMetaData,
-                    hints: parsed.hints !== false,
+                    hints: resolveHintLevel(parsed.hints, "full"),
+                    hintTypes: parsed.hintTypes,
+                    minSeverity: parsed.minSeverity,
                     provenance: parsed.provenance,
                     rights: parsed.rights,
                     forUser: parsed.forUser,
@@ -3181,14 +3416,32 @@ async function _handleToolCall(client, name, args, context) {
             case "nestr_get_nest_children": {
                 const parsed = schemas.getNestChildren.parse(args);
                 const children = await client.getNestChildren(parsed.nestId, {
+                    search: parsed.search,
                     sort: parsed.sort,
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
-                    hints: parsed.hints !== false,
+                    hints: resolveHintLevel(parsed.hints, "summary"),
+                    hintTypes: parsed.hintTypes,
+                    minSeverity: parsed.minSeverity,
+                    linkedUsers: parsed.linkedUsers,
                 });
                 return formatResult(completableResponse(compactResponse(enrichHints(children)), "children", parsed._listTitle || "Sub-items"));
             }
+            case "nestr_hints_rollup": {
+                const parsed = schemas.hintsRollup.parse(args);
+                const rollup = await client.getHintsRollup(parsed.nestId, {
+                    hintTypes: parsed.hintTypes,
+                    minSeverity: parsed.minSeverity,
+                    sampleSize: parsed.sampleSize,
+                });
+                return formatResult(rollup);
+            }
+            case "nestr_api_spec": {
+                const parsed = schemas.apiSpec.parse(args);
+                const spec = await client.getApiSpec();
+                return formatResult(summariseApiSpec(spec, parsed));
+            }
             case "nestr_create_nest": {
                 const parsed = schemas.createNest.parse(args);
                 validatePrimeLabels(parsed.labels);
@@ -3325,6 +3578,7 @@ async function _handleToolCall(client, name, args, context) {
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
+                    linkedUsers: parsed.linkedUsers,
                 });
                 return formatResult(compactResponse(roles, "role"));
             }
@@ -3381,6 +3635,7 @@ async function _handleToolCall(client, name, args, context) {
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
+                    linkedUsers: parsed.linkedUsers,
                 });
                 return formatResult(completableResponse(compactResponse(projects), "projects", parsed._listTitle || "Projects"));
             }
@@ -3763,9 +4018,7 @@ async function _handleToolCall(client, name, args, context) {
             case "nestr_list_tensions": {
                 const parsed = schemas.listTensions.parse(args);
                 const tensions = await client.listTensions(parsed.nestId, parsed.search, {
-                    // `order` is the legacy name for this option — it was never honored
-                    // by the API (which reads `sort`), so route both through sort.
-                    sort: parsed.sort ?? parsed.order,
+                    sort: parsed.sort,
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,