@nestr/mcp 0.1.97 → 0.1.99

package/build/tools/index.js

@@ -125,6 +125,40 @@ const HINT_URL_PATTERNS = [
         tool: "nestr_search",
         params: (m, sp) => ({ workspaceId: m[1], query: sp.get("search") || "" }),
     },
+    // Direct-message hints. The unread hint on a thread carries the endpoint that answers
+    // it, so these turn "3 posts you have not read" into the one call that lists them
+    // rather than a URL the model has to hand-assemble.
+    // /users/me/dm/{t}/posts → nestr_get_dm_posts (before the thread pattern)
+    {
+        pattern: /^\/users\/me\/dm\/([^/]+)\/posts$/,
+        tool: "nestr_get_dm_posts",
+        params: (m, sp) => {
+            const result = { threadId: m[1] };
+            const unread = sp.get("unread");
+            if (unread)
+                result.unread = unread === "true";
+            return result;
+        },
+    },
+    // /users/me/dm/{t} → nestr_get_dm_thread (after the deeper pattern above)
+    {
+        pattern: /^\/users\/me\/dm\/([^/]+)$/,
+        tool: "nestr_get_dm_thread",
+        params: (m, sp) => {
+            const result = { threadId: m[1] };
+            const unread = sp.get("unread");
+            if (unread)
+                result.unread = unread === "true";
+            return result;
+        },
+    },
+    // /posts/{id}/read → nestr_mark_post_read. Carried by the unread_posts hint that
+    // nests/{id}/posts returns, so acknowledging what you just read is one call.
+    {
+        pattern: /^\/posts\/([^/]+)\/read$/,
+        tool: "nestr_mark_post_read",
+        params: (m) => ({ postId: m[1] }),
+    },
     // /nests/{id}/posts → nestr_get_comments
     { pattern: /^\/nests\/([^/]+)\/posts$/, tool: "nestr_get_comments", params: (m) => ({ nestId: m[1] }) },
     // /nests/{id}/files → nestr_get_nest_files
@@ -151,8 +185,109 @@ const HINT_TYPE_TOOL_CALLS = {
             },
         };
     },
+    // `purpose` is a first-class nest field, so there is no per-label field key to pick;
+    // only the example text differs between a role and a circle.
+    no_purpose(nest) {
+        const nestId = nest._id;
+        if (!nestId)
+            return null;
+        const labels = nest.labels || [];
+        const isRole = labels.includes("circleplus-role") || labels.includes("role");
+        return {
+            tool: "nestr_update_nest",
+            params: {
+                nestId,
+                purpose: isRole
+                    ? "<purpose statement: why this role exists and the future state it works towards>"
+                    : "<purpose statement: the north star every role and project here traces back to>",
+            },
+        };
+    },
 };
 const HINT_ENDPOINT_TOOL_MAPPINGS = [
+    // Direct messages. The unread hints on a container and a thread each carry the endpoint
+    // that answers them, so these turn "3 threads you have not read" into the one call that
+    // lists them. Deeper routes first: the patterns are tried in order.
+    // Support queues. Sibling of the DM routes, so these sit alongside them.
+    {
+        method: "GET",
+        pattern: /^\/users\/me\/queues\/([^/]+)\/threads\/?$/,
+        tool: "nestr_list_queue_threads",
+        pathParamNames: ["key"],
+        bodyParams: new Set([]),
+        queryParams: { unread: "unread" },
+    },
+    {
+        method: "GET",
+        pattern: /^\/users\/me\/queues\/?$/,
+        tool: "nestr_list_queues",
+        pathParamNames: [],
+        bodyParams: new Set([]),
+    },
+    {
+        method: "GET",
+        pattern: /^\/users\/me\/dm\/([^/]+)\/posts\/?$/,
+        tool: "nestr_get_dm_posts",
+        pathParamNames: ["threadId"],
+        bodyParams: new Set([]),
+        queryParams: { unread: "unread", depth: "depth" },
+    },
+    {
+        method: "POST",
+        pattern: /^\/users\/me\/dm\/([^/]+)\/posts\/?$/,
+        tool: "nestr_post_dm_message",
+        pathParamNames: ["threadId"],
+        bodyParams: new Set(["body"]),
+    },
+    {
+        method: "POST",
+        pattern: /^\/users\/me\/dm\/([^/]+)\/escalate\/?$/,
+        tool: "nestr_escalate_to_support",
+        pathParamNames: ["threadId"],
+        bodyParams: new Set(["reason"]),
+    },
+    {
+        method: "GET",
+        pattern: /^\/users\/me\/dm\/([^/]+)\/?$/,
+        tool: "nestr_get_dm_thread",
+        pathParamNames: ["threadId"],
+        bodyParams: new Set([]),
+        queryParams: { unread: "unread" },
+    },
+    {
+        method: "PATCH",
+        pattern: /^\/users\/me\/dm\/([^/]+)\/?$/,
+        tool: "nestr_update_dm_thread",
+        pathParamNames: ["threadId"],
+        bodyParams: new Set(["title", "completed", "users"]),
+    },
+    {
+        method: "POST",
+        pattern: /^\/users\/me\/dm\/?$/,
+        tool: "nestr_start_dm_thread",
+        pathParamNames: [],
+        bodyParams: new Set(["user", "title"]),
+    },
+    {
+        method: "GET",
+        pattern: /^\/users\/me\/dm\/?$/,
+        tool: "nestr_list_dms",
+        pathParamNames: [],
+        bodyParams: new Set([]),
+        // The route spells the filter ?user=, the tool calls it withUser. unread now belongs
+        // here too: the listing is the threads themselves, so "what have I not read" is
+        // answered by this call rather than by a container's own threads route.
+        queryParams: { user: "withUser", unread: "unread" },
+    },
+    // Carried by the unread_posts hint on nests/{id}/posts, so acknowledging what you just
+    // read is one call. Works for any post, not only a DM.
+    {
+        method: "POST",
+        pattern: /^\/posts\/([^/]+)\/read\/?$/,
+        tool: "nestr_mark_post_read",
+        pathParamNames: ["postId"],
+        bodyParams: new Set([]),
+    },
     {
         method: "POST",
         pattern: /^\/nests\/?$/,
@@ -211,10 +346,18 @@ const HINT_ENDPOINT_TOOL_MAPPINGS = [
         bodyParams: new Set([]),
     },
 ];
-/** Strip optional host + /api prefix so we match against canonical routes. */
+/**
+ * Strip optional host + /api prefix so we match against canonical routes, and split the
+ * query off: the patterns describe paths, so a trailing `?unread=true` would stop every
+ * one of them matching.
+ */
 function normalizeEndpointPath(path) {
     const hostStripped = path.replace(/^https?:\/\/[^/]+/, "");
-    return hostStripped.replace(/^\/api(?=\/)/, "");
+    const [rawPath, queryString] = hostStripped.split("?");
+    return {
+        path: rawPath.replace(/^\/api(?=\/)/, ""),
+        search: new URLSearchParams(queryString || ""),
+    };
 }
 /**
  * Translate one API hint endpoint into an MCP tool-call suggestion.
@@ -226,7 +369,7 @@ export function translateEndpoint(endpoint) {
     const method = (endpoint.method || "").toUpperCase();
     if (!method)
         return null;
-    const path = normalizeEndpointPath(endpoint.path || "");
+    const { path, search } = normalizeEndpointPath(endpoint.path || "");
     for (const mapping of HINT_ENDPOINT_TOOL_MAPPINGS) {
         if (mapping.method !== method)
             continue;
@@ -237,6 +380,17 @@ export function translateEndpoint(endpoint) {
         mapping.pathParamNames.forEach((name, i) => {
             parametersExample[name] = match[i + 1];
         });
+        // "true"/"false" become booleans: every tool that takes one of these declares it as a
+        // boolean, and a string would fail schema validation on the suggested call.
+        if (mapping.queryParams) {
+            for (const [key, value] of search.entries()) {
+                const paramName = mapping.queryParams[key];
+                if (!paramName)
+                    continue;
+                parametersExample[paramName] =
+                    value === "true" || value === "false" ? value === "true" : value;
+            }
+        }
         if (mapping.extraParams)
             Object.assign(parametersExample, mapping.extraParams);
         const droppedFields = [];
@@ -278,6 +432,21 @@ export function commentPlacementNote(requestedNestId, post) {
 }
 // Enrich hints with tool call parameters so models can act on hints directly.
 // Extracts workspaceId from nest ancestors (last element) for search-based hints.
+// Canonical web URL for a nest in the Nestr app.
+// Pattern: /n/{parentId}/{id} when a parent context is known, /n/{id} otherwise.
+// Parent 'inbox' is treated as no parent — inbox is not a navigable container.
+//
+// The host comes from the API base this server was pointed at, because these URLs are
+// handed to a person and have to open on the Nestr they are using. Hardcoding the
+// production host meant a self-hosted or local deployment answered with app.nestr.io
+// links for nests that only exist on their own server — a wrong link, confidently given,
+// which is the failure this whole area keeps producing. Hint URLs do not need this:
+// Nestr sends those absolute already. This is for the URLs this server mints itself.
+export function nestrWebBase(apiBase) {
+    const base = apiBase || "https://app.nestr.io/api";
+    return base.replace(/\/api\/?$/, "").replace(/\/+$/, "") || "https://app.nestr.io";
+}
+const NESTR_WEB_BASE = nestrWebBase(process.env.NESTR_API_BASE);
 export function enrichHints(data) {
     if (!data || typeof data !== "object")
         return data;
@@ -285,12 +454,17 @@ export function enrichHints(data) {
     if (Array.isArray(data)) {
         return data.map((item) => enrichHints(item));
     }
-    // Handle wrapped responses { data: [...] }
-    if ("data" in data && Array.isArray(data.data)) {
-        return { ...data, data: enrichHints(data.data) };
+    // Handle wrapped responses { data: [...] }. Enrich the payload, then fall through so
+    // the envelope's OWN hints are enriched too: a posts response carries unread_posts
+    // beside its data, and returning here left that hint as a bare URL.
+    let subject = data;
+    if ("data" in subject && Array.isArray(subject.data)) {
+        subject = { ...subject, data: enrichHints(subject.data) };
+        if (!Array.isArray(subject.hints))
+            return subject;
     }
     // Enrich hints on this nest
-    const record = data;
+    const record = subject;
     if (Array.isArray(record.hints)) {
         // Extract workspaceId from ancestors (last element is always the workspace)
         const ancestors = record.ancestors;
@@ -308,10 +482,12 @@ export function enrichHints(data) {
             else if (hint.url) {
                 // Legacy: single URL → toolCall. Kept for backwards compatibility with
                 // hints that pre-date the endpoints[] payload.
-                let rawUrl = hint.url;
-                const apiPrefixMatch = rawUrl.match(/^https?:\/\/[^/]+\/api(\/.*)/);
-                if (apiPrefixMatch)
-                    rawUrl = apiPrefixMatch[1];
+                // Strip an optional host, then an optional /api prefix. Previously only the
+                // host-qualified form was handled, so a bare "/api/..." hint matched no pattern
+                // and was reported as unrecognized. normalizeEndpointPath does both for the
+                // endpoints[] payload; this is the same rule for the legacy url field.
+                let rawUrl = hint.url.replace(/^https?:\/\/[^/]+/, "");
+                rawUrl = rawUrl.replace(/^\/api(?=\/)/, "");
                 const [path, queryString] = rawUrl.split("?");
                 const searchParams = new URLSearchParams(queryString || "");
                 let matched = false;
@@ -340,12 +516,10 @@ export function enrichHints(data) {
             return enriched;
         });
     }
-    return data;
+    // subject, not data: the wrapped-response branch above works on a copy, so returning
+    // `data` would discard both the enriched payload and the enriched envelope hints.
+    return subject;
 }
-// Canonical web URL for a nest in the Nestr app.
-// Pattern: /n/{parentId}/{id} when a parent context is known, /n/{id} otherwise.
-// Parent 'inbox' is treated as no parent — inbox is not a navigable container.
-const NESTR_WEB_BASE = "https://app.nestr.io";
 function buildNestUrl(id, parentId) {
     if (parentId && parentId.toLowerCase() !== "inbox") {
         return `${NESTR_WEB_BASE}/n/${parentId}/${id}`;
@@ -431,7 +605,12 @@ const coerceIntArray = (schema) => z.preprocess((val) => {
 // Shared description for the sort parameter on list/fetch tools. All of these
 // endpoints honor a `sort` query param server-side (field name, '-' prefix for
 // descending) — the same fields the search `sort:` operator uses.
-const SORT_DESCRIPTION = "Field to sort by, e.g. 'title', 'createdAt', 'updatedAt', 'due', 'activityAt', 'order' (manual order). Prefix with '-' for descending. For 'recently active' ordering use '-activityAt' (last activity anywhere in the item, including its children); '-updatedAt' only reflects the item's own edits.";
+const MENTION_DESC = "Supports HTML and @mentions. Mentions MUST use literal curly braces: `@{userId:roleId}`, NOT `@userId`. Without braces nothing is linked and nobody is notified. Forms: `@{userId:roleId}` (preferred, names the role), `@{userId}`, `@{email}`, `@{circle}` (all fillers in the nearest ancestor circle).";
+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 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
 export const schemas = {
     listWorkspaces: z.object({
@@ -440,6 +619,48 @@ export const schemas = {
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number (1-indexed) for pagination"),
     }),
+    listDMs: z.object({
+        withUser: z.string().optional().describe("Only threads with this person: their user id, username or email. Use 'nestr_support' for your Nestradamus conversation. Errors if you cannot message them."),
+        unread: z.boolean().optional().describe("true returns only threads with messages you have not read"),
+        includeCompleted: z.boolean().optional().describe("true also returns closed conversations. They are left out by default."),
+        limit: z.number().optional().describe("Threads per page (default 50, max 200)"),
+        page: z.number().optional().describe("Page number, 1-based"),
+    }),
+    startDMThread: z.object({
+        user: z.string().describe("Who to message: their user id, username or email. Must be someone you share a workspace with, or already have a conversation with."),
+        title: z.string().optional().describe("Optional thread title. Defaults to a dated one, as the app uses."),
+    }),
+    listQueues: z.object({}),
+    listQueueThreads: z.object({
+        key: z.string().describe("Queue key, e.g. 'support'. From nestr_list_queues."),
+        unread: z.boolean().optional().describe("true returns only threads you have not read"),
+    }),
+    getDMThread: z.object({
+        threadId: z.string().describe("Thread id"),
+        unread: z.boolean().optional().describe("true embeds the posts you have not read, false the ones you have. Omit for the thread alone."),
+    }),
+    updateDMThread: z.object({
+        threadId: z.string().describe("Thread id"),
+        title: z.string().optional().describe("New thread title"),
+        completed: z.boolean().nullable().optional().describe("true closes the conversation, null reopens it. A closed one drops out of nestr_list_dms unless includeCompleted is set, and stays readable and postable by id. Repeating a state changes nothing."),
+        users: z.array(z.string()).optional().describe("The participant list you want, replacing the current one — read it from nestr_get_dm_thread first. Anyone you add sees the whole thread and must be someone you share a workspace with; the bot and the person who raised the thread cannot be removed. Leave a conversation by sending the list without yourself."),
+    }),
+    getDMPosts: z.object({
+        threadId: z.string().describe("Thread id"),
+        unread: z.boolean().optional().describe("true for posts you have not read, false for the ones you have. Omit for all."),
+        depth: z.union([z.number(), z.literal("all")]).optional().describe("Include posts on descendant nests"),
+    }),
+    createDMPost: z.object({
+        threadId: z.string().describe("Thread id"),
+        body: z.string().describe("Message text. Supports HTML and Markdown."),
+    }),
+    markPostRead: z.object({
+        postId: z.string().describe("Post to mark read up to. Everything up to and including it becomes read."),
+    }),
+    escalateToSupport: z.object({
+        threadId: z.string().describe("Thread id to escalate. It must be a conversation Nestradamus is in."),
+        reason: z.string().describe("One or two sentences for whoever picks this up: what is needed and what has been tried."),
+    }),
     getWorkspace: z.object({
         workspaceId: z.string().describe("Workspace ID"),
     }),
@@ -466,7 +687,7 @@ export const schemas = {
         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."),
         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 only, with rights=true. Report rights for this user id instead of the caller. Requires the caller to be an admin of the nest."),
+        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."),
         whoCan: z.string().optional().describe("Single-nest only. Comma-separated ops (read,update,delete,create) to list who can perform each on this nest."),
     }),
     explainNest: z.object({
@@ -486,7 +707,7 @@ export const schemas = {
         parentId: z.string().describe("Parent nest ID (workspace, circle, or project)"),
         title: z.string().describe("Title of the new nest (plain text, HTML stripped)"),
         description: z.string().optional().describe("The primary content field — use for project details, task context, acceptance criteria, Definition of Done, and any detailed information. Supports Markdown and HTML."),
-        purpose: z.string().optional().describe("ONLY for workspaces, circles, and roles — a short aspirational statement of the future state this entity serves. Do NOT put project details, task context, or general information here; use description instead. Supports HTML."),
+        purpose: z.string().optional().describe(PURPOSE_DESC),
         labels: coerceFromJson(z.array(z.string())).optional().describe("Label IDs to apply"),
         fields: coerceFromJson(z.record(z.unknown())).optional().describe("Structured field values to set on creation (e.g., { 'project.status': 'Current' }, { 'skill.type': 'process' }). Same shape as nestr_update_nest fields — saves a follow-up update call."),
         users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign (required for tasks/projects to associate with a person)"),
@@ -498,7 +719,7 @@ export const schemas = {
         nestId: z.string().describe("Nest ID to update"),
         title: z.string().optional().describe("New title (plain text, HTML stripped)"),
         description: z.string().optional().describe("The primary content field — use for project details, task context, acceptance criteria, and any detailed information. Supports Markdown and HTML."),
-        purpose: z.string().optional().describe("ONLY for workspaces, circles, and roles — a short aspirational statement. Do NOT put project details, task context, or general information here; use description instead. Supports HTML."),
+        purpose: z.string().optional().describe(PURPOSE_DESC),
         parentId: z.string().optional().describe("New parent ID (move nest to different location, e.g., move inbox item to a role or project)"),
         labels: coerceFromJson(z.array(z.string())).optional().describe("Label IDs to set (e.g., ['project'] to convert an item into a project)"),
         fields: coerceFromJson(z.record(z.unknown())).optional().describe("Field updates (e.g., { 'project.status': 'Current' })"),
@@ -515,12 +736,12 @@ export const schemas = {
     }),
     addComment: z.object({
         nestId: z.string().describe("Nest ID to comment on"),
-        body: z.string().describe("Comment text. Supports HTML and @mentions. **Mentions MUST be wrapped in literal curly braces** — write `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`. Without the braces the platform will not link the mention or notify the user. Forms: `@{userId:roleId}` (preferred — addresses the user in a specific role/circle), `@{userId}` (legacy — no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)."),
-        labels: z.array(z.string()).optional().describe("Optional label IDs to attach to the comment at creation time (e.g., 'decision', 'question', or a custom label ID). Personal labels are auto-scoped to the authenticated user. Use nestr_list_labels / nestr_list_personal_labels to discover IDs."),
+        body: z.string().describe(`Comment text. ${MENTION_DESC}`),
+        labels: z.array(z.string()).optional().describe("Optional label IDs to attach at creation (e.g. 'decision', 'question', or a custom ID). Personal labels are auto-scoped to the caller. Discover IDs via nestr_list_labels / nestr_list_personal_labels."),
     }),
     updateComment: z.object({
         commentId: z.string().describe("Comment ID to update"),
-        body: z.string().describe("Updated comment text. Supports HTML and @mentions. **Mentions MUST be wrapped in literal curly braces** — write `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`. Without the braces the platform will not link the mention or notify the user. Forms: `@{userId:roleId}` (preferred — addresses the user in a specific role/circle), `@{userId}` (legacy — no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)."),
+        body: z.string().describe(`Updated comment text. ${MENTION_DESC}`),
         labels: z.array(z.string()).optional().describe("Optional full set of label IDs for the comment. When provided, this REPLACES the comment's existing labels. To incrementally add or remove a single label without replacing the rest, use nestr_add_label / nestr_remove_label with the commentId as the nestId."),
     }),
     deleteComment: z.object({
@@ -582,6 +803,7 @@ export const schemas = {
     getComments: z.object({
         nestId: z.string().describe("Nest ID to get comments from. Pass a workspace ID to gather communication across the whole workspace (combine with depth='all')."),
         depth: z.union([z.number(), z.literal("all")]).optional().describe("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. Use 'all' on a workspace or circle nest to analyse large sets of communication in one call."),
+        unread: z.boolean().optional().describe("true for comments you have not read, false for the ones you have. Omit for all."),
     }),
     getCircle: z.object({
         workspaceId: z.string().describe("Workspace ID"),
@@ -743,14 +965,14 @@ export const schemas = {
         tensionId: z.string().describe("Tension ID"),
         _id: z.string().optional().describe("ID of an existing governance item to change or remove. Omit to propose a new item."),
         title: z.string().optional().describe("Title for the governance item"),
-        labels: coerceFromJson(z.array(z.string())).optional().describe("Labels defining the item type (e.g., ['role'], ['circle'], ['policy'], ['accountability'], ['domain'])"),
+        labels: coerceFromJson(z.array(z.string())).optional().describe("Item type, e.g. ['role'], ['circle'], ['policy'], ['accountability'], ['domain']"),
         description: z.string().optional().describe("The primary content field — detailed information about the item. Supports Markdown and HTML."),
-        purpose: z.string().optional().describe("ONLY for roles/circles — a short aspirational statement. Do NOT put detailed information here; use description instead. Supports HTML."),
+        purpose: z.string().optional().describe(PURPOSE_DESC),
         parentId: z.string().optional().describe("Parent ID — use to move/restructure items (e.g., move role to different circle)"),
-        users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign. For an election (with roleId), the single user being elected, e.g. [\"userId\"]."),
-        due: z.string().optional().describe("Due date / re-election date (ISO format). For an election (with roleId), the term end — omit to elect without a term."),
-        accountabilities: coerceFromJson(z.array(z.string())).optional().describe("Accountability titles to set on a role (replaces all — use children endpoint for individual management)"),
-        domains: coerceFromJson(z.array(z.string())).optional().describe("Domain titles to set on a role (replaces all — use children endpoint for individual management)"),
+        users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign. For an election (with roleId), the one user being elected."),
+        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)"),
         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." }),
@@ -760,13 +982,13 @@ export const schemas = {
         partId: z.string().describe("Part ID to modify"),
         title: z.string().optional().describe("Updated title"),
         description: z.string().optional().describe("Updated description — the primary content field. Supports Markdown and HTML."),
-        purpose: z.string().optional().describe("ONLY for roles/circles — updated aspirational statement. Do NOT put detailed information here; use description instead. Supports HTML."),
+        purpose: z.string().optional().describe(PURPOSE_DESC),
         labels: coerceFromJson(z.array(z.string())).optional().describe("Updated labels"),
         parentId: z.string().optional().describe("Updated parent ID"),
         users: coerceFromJson(z.array(z.string())).optional().describe("Updated user assignments"),
         due: z.string().optional().describe("Updated due date (ISO format)"),
-        accountabilities: coerceFromJson(z.array(z.string())).optional().describe("Updated accountabilities (replaces all — use children endpoint for individual management)"),
-        domains: coerceFromJson(z.array(z.string())).optional().describe("Updated domains (replaces all — use children endpoint for individual management)"),
+        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)"),
     }),
     removeTensionPart: z.object({
         nestId: z.string().describe("ID of the circle or role the tension belongs to"),
@@ -846,15 +1068,15 @@ export const schemas = {
         workspaceId: z.string().describe("Workspace ID to register the connector in"),
         type: z.enum(["mcp", "cli", "api"]).describe("Transport: 'mcp' (MCP server over a url), 'api' (REST endpoint over a url), or 'cli' (a command)"),
         name: z.string().describe("Unique connector name within the workspace catalog"),
-        config: coerceFromJson(z.record(z.unknown())).optional().describe("Per-type transport config, no secret. mcp/api need a url (e.g., { url: 'https://...' }); cli needs a command (e.g., { command: 'some-cli' }). Optional non-secret headers go under headers."),
-        capabilities: coerceFromJson(z.record(z.unknown())).optional().describe("Capability descriptor: { discover: boolean, tools: [{ name, description, inputSchema }] }. discover:true lets the connector self-describe its tools at runtime."),
-        exposure: coerceFromJson(z.record(z.unknown())).optional().describe("Exposure policy deciding which owners may bind: { userAgent: boolean, domainGated: boolean }. Set domainGated:true to allow binding to a role's domain."),
-        authStrategy: z.enum(["secret", "oauth2"]).optional().describe("How a principal connects: 'secret' (a one-time secret captured via the Connect button) or 'oauth2'. The agent never sees the secret."),
+        config: coerceFromJson(z.record(z.unknown())).optional().describe("Transport config, no secret. mcp/api need a url, cli a command. Optional non-secret headers go under headers."),
+        capabilities: coerceFromJson(z.record(z.unknown())).optional().describe("{ discover: boolean, tools: [{ name, description, inputSchema }] }. discover:true lets the connector self-describe its tools at runtime."),
+        exposure: coerceFromJson(z.record(z.unknown())).optional().describe("Which owners may bind: { userAgent: boolean, domainGated: boolean }. domainGated:true allows binding to a role's domain."),
+        authStrategy: z.enum(["secret", "oauth2"]).optional().describe("How a principal connects: 'secret' (one-time, via the Connect button) or 'oauth2'. The agent never sees it."),
     }),
     bindConnector: z.object({
         workspaceId: z.string().describe("Workspace ID the connector and owner belong to"),
         connectorId: z.string().describe("ID of an enabled connector from nestr_list_connectors"),
-        ownerType: z.enum(["user", "agent", "workspace", "role-domain"]).describe("Owner type. 'role-domain' binds the connector to a role's domain so the role can use it and a credentials field is materialised on the domain."),
+        ownerType: z.enum(["user", "agent", "workspace", "role-domain"]).describe("Owner type. 'role-domain' binds to a role's domain, materialising a credentials field there."),
         ownerId: z.string().describe("Owner ID. user/agent: the user ID. workspace: the workspace ID. role-domain: the domain nest ID."),
     }),
     // File attachments (a comment id works as the nestId — files are keyed by nestId)
@@ -887,15 +1109,15 @@ const destructive = { annotations: { readOnlyHint: false, destructiveHint: true
 export const toolDefinitions = [
     {
         name: "nestr_help",
-        description: "Get Nestr documentation. Three modes: (1) internal MCP-flavoured topic — pass `topic` with one of the curated keys (search, labels, nest-model, inbox, daily-plan, notifications, insights, tension-processing, skills, mcp-apps, authentication, scrum, okr, ...); use topic 'topics' for the full list. (2) Help-article fetch — pass `topic` with a slug from nestr.io/help/articles/<slug>; returns the article as markdown plus a numbered list of its images (with URLs and captions). Images are NOT attached by default. Pass `includeImages: true` to also attach the first `maxImages` (default 3, max 6) content screenshots as renderable image blocks (downscaled; decorative header/thumbnail/uncaptioned images skipped), or `imageIndexes: [..]` to attach specific ones from the numbered list (e.g. a burndown chart further down, ignoring the cap). Use images when the user wants to *see* how something looks. The tool tries internal topics first, then falls back to article fetch. (3) Help-article search — pass `search` with a free-text query; returns ranked matches, each with a title and one-line summary. Search tolerates typos and common synonyms (e.g. kanban/sprint→scrum). Every response opens with a 'Resolved as:' line stating which mode answered, and internal topics and articles cross-link to each other. Call this before unfamiliar operations. Auth: none required.",
+        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.",
         inputSchema: {
             type: "object",
             properties: {
                 topic: { type: "string", description: "Internal topic key or help-article slug. Use 'topics' for the full list of internal topics." },
                 search: { type: "string", description: "Free-text query against the public help articles. Returns slugs to fetch via `topic`." },
-                includeImages: { type: "boolean", description: "Help-article mode only. Default false (markdown + numbered image-URL list, no image blocks). Set true to attach the first maxImages content screenshots as inline image content (base64, downscaled). Decorative header/thumbnail/uncaptioned images are never auto-attached — use imageIndexes for those. Ignored for internal topics and search." },
-                imageIndexes: { type: "array", items: { type: "integer", minimum: 0 }, description: "Help-article mode only. Attach specific screenshots by their [index] from the numbered 'Images in this article' list in a prior response's footer, e.g. [4,5,6]. Overrides the default selection and the maxImages cap; attaches exactly these indexes in order. Ignored for internal topics and search." },
-                maxImages: { type: "integer", minimum: 1, description: "Help-article mode only. Cap on screenshots in the default selection (first N content images). Default 3, max 6. Ignored when imageIndexes is provided." },
+                includeImages: { type: "boolean", description: "Article mode. Default false (markdown plus a numbered image-URL list). True attaches the first maxImages content screenshots inline, downscaled. Header, thumbnail and uncaptioned images are never auto-attached; reach those with imageIndexes." },
+                imageIndexes: { type: "array", items: { type: "integer", minimum: 0 }, description: "Article mode. Attach screenshots by [index] from the numbered list in a prior response, e.g. [4,5,6]. Overrides the default selection and the maxImages cap, attaching exactly these in order." },
+                maxImages: { type: "integer", minimum: 1, description: "Article mode. Caps the default selection (first N content images). Default 3, max 6. Ignored when imageIndexes is set." },
             },
         },
         ...readOnly,
@@ -919,7 +1141,7 @@ export const toolDefinitions = [
                 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) for pagination" },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for bulk/index operations." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
             },
         },
         ...readOnly,
@@ -931,7 +1153,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 workspaceId: { type: "string", description: "Workspace ID" },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
             },
             required: ["workspaceId"],
         },
@@ -984,10 +1206,10 @@ export const toolDefinitions = [
                 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')" },
                 sort: { type: "string", description: `${SORT_DESCRIPTION} Takes precedence over sort:/sort-order: operators in the query.` },
-                limit: { type: "number", description: "Max results per page. Do NOT set on first call - let API return default with meta.total count showing total matches." },
+                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" },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for bulk/index operations." },
-                _listTitle: { type: "string", description: "Short descriptive title for the list UI header (2-4 words, e.g., \"Marketing projects\", \"Overdue tasks\", \"Urgent work\"). Describe WHAT is being shown, not the query syntax." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
+                _listTitle: { type: "string", description: "Short title for the list UI header, 2-4 words, e.g. Marketing projects. Say what is shown, not the query." },
             },
             required: ["workspaceId", "query"],
         },
@@ -1001,14 +1223,14 @@ export const toolDefinitions = [
         inputSchema: {
             type: "object",
             properties: {
-                nestId: { type: "string", description: "Nest ID, or comma-separated IDs to fetch multiple nests at once (e.g., 'id1,id2,id3'). Keep total URL under 2000 chars." },
+                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: "Include contextual hints (default: true). Set to false for bulk lookups where you only need structural data." },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size." },
-                provenance: { type: "boolean", description: "Single-nest only. Include field/property provenance: 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 only. Include the caller's composed rights on the nest (self read/update/delete) plus a deny trace naming the profiles that block each op, and why." },
-                forUser: { type: "string", description: "Single-nest only, with rights=true. Report rights for this user id instead of the caller. Requires the caller to be an admin of the nest." },
-                whoCan: { type: "string", description: "Single-nest only. Comma-separated ops (read,update,delete,create): list the users who can perform each op on this nest (admins + role-holders), with contact for admin callers." },
+                hints: { type: "boolean", description: "Contextual hints, default true. False for bulk lookups needing only structure." },
+                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." },
+                forUser: { type: "string", description: "Single nest, with rights=true. Rights for this user id instead of the caller. Caller must be a nest admin." },
+                whoCan: { type: "string", description: "Single nest. Comma-separated ops (read,update,delete,create): who can perform each (admins + role-holders), with contact for admin callers." },
             },
             required: ["nestId"],
         },
@@ -1039,7 +1261,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)" },
                 hints: { type: "boolean", description: "Include contextual hints (default: true). Set to false for large result sets or bulk operations." },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for bulk/index operations." },
+                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." },
             },
             required: ["nestId"],
@@ -1050,14 +1272,14 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_create_nest",
-        description: "Create a nest under a parent. Use labels to define type (e.g., ['project'], ['role']). Apply at most ONE prime label per nest (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback, userstory, sprint, epic, milestone) — they define the nest's core identity and cannot coexist. Sole exception: userstory may pair with project (userstory implies project); sprint/epic/milestone may not, and stories link to those containers via graph relations instead. For governance changes in established workspaces, prefer the tension flow. See nestr_help('labels') for available types.",
+        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').`,
         inputSchema: {
             type: "object",
             properties: {
                 parentId: { type: "string", description: "Parent nest ID (workspace, circle, or project)" },
                 title: { type: "string", description: "Title of the new nest (plain text, HTML tags stripped)" },
-                description: { type: "string", description: "The primary content field — use for project details, task context, acceptance criteria, DoD, and any detailed information. Use fields (e.g., project.status) for structured data and comments for progress updates. Supports Markdown and HTML." },
-                purpose: { type: "string", description: "ONLY for workspaces, circles, and roles — a short aspirational statement of the future state this entity serves. Do NOT put project details, task context, or general information here; use description instead. Supports HTML." },
+                description: { type: "string", description: CONTENT_DESC },
+                purpose: { type: "string", description: PURPOSE_DESC },
                 labels: {
                     type: "array",
                     items: { type: "string" },
@@ -1093,14 +1315,14 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_update_nest",
-        description: "Update nest properties. Set parentId to move. Only send fields you want to change. When replacing `labels`, keep at most ONE prime label (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback, userstory, sprint, epic, milestone) — they define the nest's core identity. Sole exception: userstory may pair with project (userstory implies project). For governance changes, prefer tensions. See nestr_help('nest-model') for fields and data namespacing.",
+        description: `Update nest properties. Set parentId to move. Send only what changes. When replacing labels: ${PRIME_LABEL_RULE} Prefer tensions for governance. See nestr_help('nest-model') for fields and data namespacing.`,
         inputSchema: {
             type: "object",
             properties: {
                 nestId: { type: "string", description: "Nest ID to update" },
                 title: { type: "string", description: "New title (plain text, HTML tags stripped)" },
-                description: { type: "string", description: "The primary content field — use for details, context, acceptance criteria, and any information about the nest. Use fields for structured data, comments for progress. Supports Markdown and HTML." },
-                purpose: { type: "string", description: "ONLY for workspaces, circles, and roles — a short aspirational statement. Do NOT put project details, task context, or general information here; use description instead. Supports HTML." },
+                description: { type: "string", description: CONTENT_DESC },
+                purpose: { type: "string", description: PURPOSE_DESC },
                 parentId: { type: "string", description: "New parent ID (move nest to different location)" },
                 labels: {
                     type: "array",
@@ -1161,16 +1383,16 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_comment",
-        description: "Add a comment to a nest. Supports HTML and @mentions — **mentions MUST be wrapped in literal curly braces** (e.g. `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`); without the braces the user is not notified. Prefer `@{userId:roleId}` so the recipient knows which role they're being addressed in. Use for progress updates and discussion. Optionally attach labels at creation time via the `labels` parameter.",
+        description: "Add a comment to a nest, for progress updates and discussion. Mentions need literal curly braces, see `body`. Optionally attach labels at creation.",
         inputSchema: {
             type: "object",
             properties: {
-                nestId: { type: "string", description: "ID of the nest or conversation the comment belongs to. Passing a comment ID instead replies to that comment, inside its thread. A direct-message conversation is flat and holds no threads, so a message ID there is moved onto the conversation and the response says where the comment landed." },
-                body: { type: "string", description: "Comment text. Supports HTML and @mentions. **Mentions MUST be wrapped in literal curly braces** — write `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`. Without the braces the platform will not link the mention or notify the user. Forms: `@{userId:roleId}` (preferred — addresses the user in a specific role/circle), `@{userId}` (legacy — no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)." },
+                nestId: { type: "string", description: "Nest or conversation the comment belongs to. A comment ID instead replies inside that thread. Direct-message conversations are flat, so a message ID there lands on the conversation and the response says where." },
+                body: { type: "string", description: `Comment text. ${MENTION_DESC}` },
                 labels: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Optional label IDs to attach to the comment at creation time (e.g., 'decision', 'question', or a custom label ID). Personal labels are auto-scoped to the authenticated user. Use nestr_list_labels / nestr_list_personal_labels to discover IDs.",
+                    description: "Optional label IDs to attach at creation (e.g. 'decision', 'question', or a custom ID). Personal labels are auto-scoped to the caller. Discover IDs via nestr_list_labels / nestr_list_personal_labels.",
                 },
             },
             required: ["nestId", "body"],
@@ -1184,7 +1406,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 commentId: { type: "string", description: "Comment ID to update" },
-                body: { type: "string", description: "Updated comment text. Supports HTML and @mentions. **Mentions MUST be wrapped in literal curly braces** — write `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`. Without the braces the platform will not link the mention or notify the user. Forms: `@{userId:roleId}` (preferred — addresses the user in a specific role/circle), `@{userId}` (legacy — no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)." },
+                body: { type: "string", description: `Updated comment text. ${MENTION_DESC}` },
                 labels: {
                     type: "array",
                     items: { type: "string" },
@@ -1217,7 +1439,7 @@ export const toolDefinitions = [
                 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)" },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for large workspaces." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
             },
             required: ["workspaceId"],
         },
@@ -1234,7 +1456,7 @@ export const toolDefinitions = [
                 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)" },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for large circles." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
             },
             required: ["workspaceId", "circleId"],
         },
@@ -1262,12 +1484,146 @@ export const toolDefinitions = [
                 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)" },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for large workspaces." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
             },
             required: ["workspaceId"],
         },
         ...readOnly,
     },
+    // ---- Direct messages ----
+    // A thread is the unit and its id is the whole address. There is no container to fetch
+    // first: start from nestr_list_dms, optionally narrowed to one person with withUser.
+    {
+        name: "nestr_list_dms",
+        description: "List your open direct-message threads, most recently posted first. Closed ones are left out unless includeCompleted is set. Pass withUser to see only the ones with a particular person; withUser:'nestr_support' is your Nestradamus conversation. Each thread carries participants, so a flat list still tells you who you are talking to.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                withUser: { type: "string", description: "Only threads with this person: user id, username or email" },
+                unread: { type: "boolean", description: "Only threads with messages you have not read" },
+                includeCompleted: { type: "boolean", description: "Also return closed conversations (left out by default)" },
+                limit: { type: "number", description: "Threads per page (default 50, max 200)" },
+                page: { type: "number", description: "Page number, 1-based" },
+            },
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_start_dm_thread",
+        description: "Start a new direct-message thread with someone. Use it for a new subject rather than reopening an old thread. You must share a workspace with them, or already have a conversation with them.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                user: { type: "string", description: "Who to message: user id, username or email" },
+                title: { type: "string", description: "Optional title. Defaults to a dated one, as the app uses." },
+            },
+            required: ["user"],
+        },
+        ...mutating,
+    },
+    // ---- Support queues ----
+    // A queue is a label on threads across many DM spaces, not a space itself. It hands
+    // back thread ids, and a thread id is the whole address: nestr_get_dm_thread /
+    // nestr_get_dm_posts take it directly.
+    {
+        name: "nestr_list_queues",
+        description: "List the support queues you can see: the ones you monitor, plus any you have raised a thread in. Each carries `subscribed`, which decides what nestr_list_queue_threads returns for you.",
+        inputSchema: { type: "object", properties: {} },
+        ...readOnly,
+    },
+    {
+        name: "nestr_list_queue_threads",
+        description: "List threads in a support queue, most recently posted first. If you subscribe to the queue you get every thread in it; otherwise you get only the ones you raised, which is how you find your own open support tickets. Pass unread:true for just what has moved. Read one with nestr_get_dm_thread using the id you get back.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                key: { type: "string", description: "Queue key, e.g. 'support'" },
+                unread: { type: "boolean", description: "Only threads you have not read" },
+            },
+            required: ["key"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_get_dm_thread",
+        description: "Get a direct-message thread as a nest, with hints. Pass unread:true to embed the posts you have not read in the same call, which is usually what you want when picking a thread back up.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string", description: "Thread id" },
+                unread: { type: "boolean", description: "true embeds unread posts, false embeds read ones" },
+            },
+            required: ["threadId"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_update_dm_thread",
+        description: "Update a direct-message thread: rename it, close or reopen it, or change who is in it. Send only the keys you want changed, as with nestr_update_nest. completed:true closes a conversation once it is dealt with, which takes it out of nestr_list_dms without losing it; completed:null reopens. `users` is the participant list you want, so read the thread first and send the list with someone added or removed; the bot and the person who raised the thread cannot be removed. Answers with the updated thread.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string", description: "Thread id" },
+                title: { type: "string", description: "New thread title" },
+                completed: { type: ["boolean", "null"], description: "true closes the conversation, null reopens it" },
+                users: { type: "array", items: { type: "string" }, description: "The participant list you want, replacing the current one" },
+            },
+            required: ["threadId"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_get_dm_posts",
+        description: "Read the posts in a direct-message thread, oldest first, each with its nested replies. Pass unread:true for just what is new, false for the rest.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string", description: "Thread id" },
+                unread: { type: "boolean", description: "true for unread posts, false for read ones. Omit for all." },
+                depth: { type: ["number", "string"], description: "Include posts on descendant nests, or 'all'" },
+            },
+            required: ["threadId"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_post_dm_message",
+        description: "Post a message into a direct-message thread.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string", description: "Thread id" },
+                body: { type: "string", description: "Message text. Supports HTML and Markdown." },
+            },
+            required: ["threadId", "body"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_mark_post_read",
+        description: "Mark a conversation read up to and including this post. Works for any post, not only direct messages. The marker never moves backwards, so calling it on an older post is harmless.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                postId: { type: "string", description: "Post to mark read up to" },
+            },
+            required: ["postId"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_escalate_to_support",
+        description: "Bring a human from Nestr support into a Nestradamus conversation. Use it when the person asks for a human, when you have answered the wrong question more than once, or when something needs Nestr staff to look at their account. Find the thread with nestr_list_dms({withUser:'nestr_support'}). Safe to call twice; a thread already waiting stays as it is. Only works on a conversation Nestradamus is in.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string", description: "Thread id to escalate" },
+                reason: { type: "string", description: "One or two sentences for whoever picks this up: what is needed and what has been tried. They can read the thread, so do not summarise it." },
+            },
+            required: ["threadId", "reason"],
+        },
+        ...mutating,
+    },
     {
         name: "nestr_get_insights",
         description: "Get organizational health metrics and trends. Each metric has currentValue and compareValue for direction. Pro plan: filter by circle (nestId) or user (userId). Requires Insights app. See nestr_help('insights').",
@@ -1337,7 +1693,7 @@ export const toolDefinitions = [
                 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)" },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for large workspaces." },
+                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." },
             },
             required: ["workspaceId"],
@@ -1347,7 +1703,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_get_comments",
-        description: "Get comments and discussion history on a nest, including full nested reply threads. By default returns only comments posted directly on the given nest. Widen with depth to also include comments on descendant nests, or pass a workspace/circle nest ID with depth='all' to gather large sets of communication for analysis.",
+        description: "Get comments and discussion history on a nest, including full nested reply threads. By default returns only comments posted directly on the given nest. Widen with depth to also include comments on descendant nests, or pass a workspace/circle nest ID with depth='all' to gather large sets of communication for analysis. Carries an unread_posts hint when you have not read everything; nestr_mark_post_read acknowledges up to a given post, on any nest, not just direct messages.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1369,7 +1725,7 @@ export const toolDefinitions = [
             properties: {
                 workspaceId: { type: "string", description: "Workspace ID" },
                 circleId: { type: "string", description: "Circle ID" },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
             },
             required: ["workspaceId", "circleId"],
         },
@@ -1390,7 +1746,16 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_workspace_user",
-        description: "Add a user to a workspace by email. Creates account if needed.",
+        description: "Adds a user to a workspace by email, creating the account if needed. It SENDS A REAL INVITE "
+            + "EMAIL, so confirm with the requester first. Covers seats, membership, plan headcount, adding "
+            + "a colleague. It provisions only domains the workspace added and Nestr verified: personal "
+            + "providers (gmail.com) are always refused, and an added domain stays refused until verified. "
+            + "That limits this tool, not the workspace. The in-app invite (Workspace settings, Users, "
+            + "\"Invite users\") accepts any address with no domain check, so offer it first on a refusal. "
+            + "NEVER suggest clearing the workspace domain list: it keeps the requirement, kills the only "
+            + "way to meet it, and breaks auto-join. Suggest adding a domain only when they control that "
+            + "company domain. Nestr review "
+            + "takes up to 24 hours.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1452,7 +1817,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 completedAfter: { type: "string", description: "Include completed items from this date (ISO format). If omitted, only non-completed items are returned. For reordering, this default is usually sufficient — nestr_reorder_inbox only requires the IDs of items you want to reposition." },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
             },
         },
         _meta: completableListUi,
@@ -1478,7 +1843,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 nestId: { type: "string", description: "Inbox item ID" },
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
             },
             required: ["nestId"],
         },
@@ -1594,7 +1959,7 @@ export const toolDefinitions = [
         inputSchema: {
             type: "object",
             properties: {
-                stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size." },
+                stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
             },
         },
         _meta: completableListUi,
@@ -1840,7 +2205,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_tension_part",
-        description: "Add a governance proposal part to a tension. Four modes: (1) propose a new item — omit _id, provide title/labels/etc.; (2) propose changes to an existing item — provide _id plus the fields to change (note: editing a role this way copies its existing accountabilities/domains into the proposal, so it reads as a full role edit); (3) propose deletion of an existing item — provide _id and removeNest:true; (4) hold an election — provide roleId (the electable role to fill) plus users:[userId] and optional due (term), which assigns/reconfirms the role's filler WITHOUT changing its accountabilities/domains. See nestr_help('tension-processing').",
+        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').",
         inputSchema: {
             type: "object",
             properties: {
@@ -1848,16 +2213,16 @@ export const toolDefinitions = [
                 tensionId: { type: "string", description: "Tension ID" },
                 _id: { type: "string", description: "ID of an existing governance item to change or remove. Omit to propose a new item." },
                 title: { type: "string", description: "Title for the governance item" },
-                labels: { type: "array", items: { type: "string" }, description: "Labels defining the item type (e.g., ['role'], ['circle'], ['policy'], ['accountability'], ['domain'])" },
+                labels: { type: "array", items: { type: "string" }, description: "Item type, e.g. ['role'], ['circle'], ['policy'], ['accountability'], ['domain']" },
                 description: { type: "string", description: "The primary content field — detailed information about the item. Supports Markdown and HTML." },
-                purpose: { type: "string", description: "ONLY for roles/circles — a short aspirational statement. Do NOT put detailed information here; use description instead. Supports HTML." },
+                purpose: { type: "string", description: PURPOSE_DESC },
                 parentId: { type: "string", description: "Parent ID — use to move/restructure items (e.g., move role to different circle)" },
-                users: { type: "array", items: { type: "string" }, description: "User IDs to assign. For an election (with roleId), the single user being elected, e.g. [\"userId\"]." },
-                due: { type: "string", description: "Due date / re-election date (ISO format). For an election (with roleId), the term end — omit to elect without a term." },
-                accountabilities: { type: "array", items: { type: "string" }, description: "Accountability titles to set on a role (replaces all — use children endpoint for individual management)" },
-                domains: { type: "array", items: { type: "string" }, description: "Domain titles to set on a role (replaces all — use children endpoint for individual management)" },
-                roleId: { type: "string", description: "Hold an ELECTION: the electable role to fill (Facilitator/Secretary/Rep Link or any electable role). Assigns/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: { type: "boolean", description: "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." },
+                users: { type: "array", items: { type: "string" }, description: "User IDs to assign. For an election (with roleId), the one user being elected." },
+                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)" },
+                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." },
             },
             required: ["nestId", "tensionId"],
         },
@@ -1874,13 +2239,13 @@ export const toolDefinitions = [
                 partId: { type: "string", description: "Part ID to modify" },
                 title: { type: "string", description: "Updated title" },
                 description: { type: "string", description: "Updated description — the primary content field. Supports Markdown and HTML." },
-                purpose: { type: "string", description: "ONLY for roles/circles — updated aspirational statement. Do NOT put detailed information here; use description instead. Supports HTML." },
+                purpose: { type: "string", description: PURPOSE_DESC },
                 labels: { type: "array", items: { type: "string" }, description: "Updated labels" },
                 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)" },
-                accountabilities: { type: "array", items: { type: "string" }, description: "Updated accountabilities (replaces all — use children endpoint for individual management)" },
-                domains: { type: "array", items: { type: "string" }, description: "Updated domains (replaces all — use children endpoint for individual management)" },
+                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)" },
             },
             required: ["nestId", "tensionId", "partId"],
         },
@@ -2057,7 +2422,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_register_connector",
-        description: "Register a connector in the workspace catalog: a reusable mcp / cli / api template that holds no secret. Workspace-admin only. A non-admin caller gets AUTH_SCOPE_INSUFFICIENT (call nestr_diagnose on any auth error). Provide type ('mcp' or 'api' need a url in config; 'cli' needs a command) and a unique name; optionally capabilities, exposure ({ userAgent, domainGated }), and authStrategy ('secret' or 'oauth2'). This only creates the template. Typical flow: register here, then bind it to a role's domain with nestr_bind_connector, then a human or agent connects the account via the credentials field's Connect button. The secret is captured out-of-band through that button, never by the agent.",
+        description: "Register a connector in the workspace catalog: a reusable mcp/cli/api template holding no secret. Workspace-admin only; a non-admin gets AUTH_SCOPE_INSUFFICIENT (call nestr_diagnose on any auth error). Give type ('mcp' and 'api' need a url in config, 'cli' a command) and a unique name; optionally capabilities, exposure, authStrategy. This creates the template only. Flow: register, bind to a role's domain with nestr_bind_connector, then a human or agent connects the account via the credentials field's Connect button. The secret is captured out-of-band, never by the agent.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2070,20 +2435,20 @@ export const toolDefinitions = [
                 name: { type: "string", description: "Unique connector name within the workspace catalog" },
                 config: {
                     type: "object",
-                    description: "Per-type transport config, no secret. mcp/api need a url (e.g., { url: 'https://...' }); cli needs a command (e.g., { command: 'some-cli' }). Optional non-secret headers go under headers.",
+                    description: "Transport config, no secret. mcp/api need a url, cli a command. Optional non-secret headers go under headers.",
                 },
                 capabilities: {
                     type: "object",
-                    description: "Capability descriptor: { discover: boolean, tools: [{ name, description, inputSchema }] }. discover:true lets the connector self-describe its tools at runtime.",
+                    description: "{ discover: boolean, tools: [{ name, description, inputSchema }] }. discover:true lets the connector self-describe its tools at runtime.",
                 },
                 exposure: {
                     type: "object",
-                    description: "Exposure policy deciding which owners may bind: { userAgent: boolean, domainGated: boolean }. Set domainGated:true to allow binding to a role's domain.",
+                    description: "Which owners may bind: { userAgent: boolean, domainGated: boolean }. domainGated:true allows binding to a role's domain.",
                 },
                 authStrategy: {
                     type: "string",
                     enum: ["secret", "oauth2"],
-                    description: "How a principal connects: 'secret' (a one-time secret captured via the Connect button) or 'oauth2'. The agent never sees the secret.",
+                    description: "How a principal connects: 'secret' (one-time, via the Connect button) or 'oauth2'. The agent never sees it.",
                 },
             },
             required: ["workspaceId", "type", "name"],
@@ -2092,7 +2457,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_bind_connector",
-        description: "Bind a registered connector to an owner so that owner can use it. Owner types: 'user' or 'agent' (ownerId is the user ID), 'workspace' (ownerId is the workspace ID), or 'role-domain' (ownerId is the domain nest ID). A 'role-domain' owner also materialises a credentials field on the domain nest, so the role can use the connector and the Connect button renders there; the response then includes credentialsField { domainId, fieldId, fieldCode }. After binding, a human or agent connects the account via that Connect button. The secret is captured out-of-band and is never seen by the agent. Workspace-admin only: a non-admin caller gets AUTH_SCOPE_INSUFFICIENT. The connector must already be registered (nestr_register_connector) and enabled.",
+        description: "Bind a registered connector to an owner so that owner can use it. Owner types: 'user' or 'agent' (ownerId is the user ID), 'workspace' (the workspace ID), 'role-domain' (the domain nest ID). A role-domain binding also materialises a credentials field on the domain nest, so the Connect button renders there and the response carries credentialsField { domainId, fieldId, fieldCode }. A human or agent then connects the account through that button; the secret is captured out-of-band, never seen by the agent. Workspace-admin only, and the connector must already be registered and enabled.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2101,7 +2466,7 @@ export const toolDefinitions = [
                 ownerType: {
                     type: "string",
                     enum: ["user", "agent", "workspace", "role-domain"],
-                    description: "Owner type. 'role-domain' binds the connector to a role's domain so the role can use it and a credentials field is materialised on the domain.",
+                    description: "Owner type. 'role-domain' binds to a role's domain, materialising a credentials field there.",
                 },
                 ownerId: {
                     type: "string",
@@ -2306,7 +2671,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}". Try broader terms or a synonym, or call nestr_help({ topic: "topics" }) for internal MCP topics.` }] };
+                            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.` }] };
                         }
                         // Enrich the top hits with a title + one-line summary so the caller
                         // can pick the right article without a blind fetch. Best-effort:
@@ -2732,8 +3097,12 @@ async function _handleToolCall(client, name, args, context) {
                 const parsed = schemas.getComments.parse(args);
                 const comments = await client.getNestPosts(parsed.nestId, {
                     depth: parsed.depth,
+                    unread: parsed.unread,
                 });
-                return formatResult(comments);
+                // enrichHints turns the unread_posts hint's endpoint into a nestr_mark_post_read
+                // call. Without it the hint still arrives, but as a raw URL the model has to
+                // recognise and hand-assemble.
+                return formatResult(enrichHints(comments));
             }
             case "nestr_get_circle": {
                 const parsed = schemas.getCircle.parse(args);
@@ -2830,6 +3199,92 @@ async function _handleToolCall(client, name, args, context) {
                 });
                 return formatResult({ message: "Personal label created successfully", label });
             }
+            // Direct messages
+            case "nestr_list_dms": {
+                const parsed = schemas.listDMs.parse(args);
+                const result = await client.listDMs({
+                    withUser: parsed.withUser,
+                    unread: parsed.unread,
+                    includeCompleted: parsed.includeCompleted,
+                    limit: parsed.limit,
+                    page: parsed.page,
+                });
+                return formatResult({ threads: result });
+            }
+            case "nestr_start_dm_thread": {
+                const parsed = schemas.startDMThread.parse(args);
+                const result = await client.createDMThread(parsed.user, parsed.title);
+                return formatResult({ message: "Thread started", thread: result });
+            }
+            case "nestr_list_queues": {
+                schemas.listQueues.parse(args ?? {});
+                const result = await client.listQueues();
+                return formatResult({ queues: result });
+            }
+            case "nestr_list_queue_threads": {
+                const parsed = schemas.listQueueThreads.parse(args);
+                const result = await client.listQueueThreads(parsed.key, { unread: parsed.unread });
+                return formatResult(enrichHints(result));
+            }
+            case "nestr_get_dm_thread": {
+                const parsed = schemas.getDMThread.parse(args);
+                const result = await client.getDMThread(parsed.threadId, { unread: parsed.unread });
+                return formatResult(enrichHints(result));
+            }
+            case "nestr_update_dm_thread": {
+                const parsed = schemas.updateDMThread.parse(args);
+                // `completed` is meaningful as null, so presence is the test rather than truth.
+                const setsCompleted = args !== null
+                    && typeof args === "object"
+                    && Object.prototype.hasOwnProperty.call(args, "completed");
+                if (parsed.title === undefined && !setsCompleted && parsed.users === undefined) {
+                    throw new Error("Pass at least one of title, completed or users.");
+                }
+                const result = await client.updateDMThread(parsed.threadId, {
+                    ...(parsed.title !== undefined ? { title: parsed.title } : {}),
+                    ...(setsCompleted ? { completed: parsed.completed ?? null } : {}),
+                    ...(parsed.users !== undefined ? { users: parsed.users } : {}),
+                });
+                return formatResult({
+                    message: setsCompleted && parsed.completed
+                        ? "Conversation closed"
+                        : "Thread updated",
+                    thread: result,
+                });
+            }
+            case "nestr_get_dm_posts": {
+                const parsed = schemas.getDMPosts.parse(args);
+                const result = await client.getDMPosts(parsed.threadId, {
+                    unread: parsed.unread,
+                    depth: parsed.depth,
+                });
+                return formatResult(enrichHints(result));
+            }
+            case "nestr_post_dm_message": {
+                const parsed = schemas.createDMPost.parse(args);
+                const result = await client.createDMPost(parsed.threadId, parsed.body);
+                return formatResult({ message: "Message posted", post: result });
+            }
+            case "nestr_mark_post_read": {
+                const parsed = schemas.markPostRead.parse(args);
+                const result = await client.markPostRead(parsed.postId);
+                return formatResult({ message: "Marked read", read: result });
+            }
+            case "nestr_escalate_to_support": {
+                const parsed = schemas.escalateToSupport.parse(args);
+                const result = await client.escalateDMThread(parsed.threadId, parsed.reason);
+                const { alreadyQueued, statusMessagePosted } = result;
+                let message = "A human has been brought in. Tell them so, and keep helping in the meantime.";
+                if (alreadyQueued) {
+                    message = "Already with a human; nothing more to do.";
+                }
+                else if (statusMessagePosted) {
+                    // Nestr posted its own confirmation into the thread, so saying it again is the
+                    // double message this flag exists to avoid.
+                    message = "A human has been brought in and the thread already says so. Do not repeat it; carry on helping.";
+                }
+                return formatResult({ message, escalation: result });
+            }
             // Reorder tools
             case "nestr_reorder_nest": {
                 const parsed = schemas.reorderNest.parse(args);