@nestr/mcp 0.1.96 → 0.1.98

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
@@ -135,6 +169,46 @@ const HINT_URL_PATTERNS = [
     { pattern: /^\/nests\/([^/]+)$/, tool: "nestr_get_nest", params: (m) => ({ nestId: m[1] }) },
 ];
 const HINT_TYPE_TOOL_CALLS = {
+    // Raised by POST /connectors when a hand-written url points at a vendor the
+    // deployment ships a template for. The follow-up is to look at the template,
+    // not to re-register blindly: the connector just created may be exactly what
+    // the caller wanted, and only they can say. The hint carries its own ids, so
+    // this works on a catalog entry rather than needing nest ancestors.
+    connector_template_available(record) {
+        const hints = record.hints || [];
+        const hint = hints.find((h) => { return h.type === "connector_template_available"; });
+        const workspaceId = (hint && hint.workspaceId) || record.workspaceId;
+        if (!workspaceId)
+            return null;
+        return {
+            tool: "nestr_list_connector_templates",
+            params: { workspaceId },
+        };
+    },
+    // Raised by GET /connector-templates on the response that LISTS them, because
+    // listing turned out not to be enough. A caller that could see the Xero
+    // template still hand-built a connector from what the template told it, and a
+    // hand-built copy carries no settingsKey, no OAuth client and whatever
+    // endpoint the model believed, so it authorises and then fails at first use.
+    // The follow-up here is the register call itself, pre-filled with the template
+    // id, so using the template is one call rather than a thing to remember.
+    connector_template_create(record) {
+        const hints = record.hints || [];
+        const hint = hints.find((h) => { return h.type === "connector_template_create"; });
+        if (!hint)
+            return null;
+        const workspaceId = hint.workspaceId || record.workspaceId;
+        if (!workspaceId)
+            return null;
+        const ids = hint.templateIds || [];
+        return {
+            tool: "nestr_register_connector",
+            params: {
+                workspaceId,
+                templateId: ids.length === 1 ? ids[0] : "<id of the template you want, from this list>",
+            },
+        };
+    },
     no_strategy(nest) {
         const nestId = nest._id;
         if (!nestId)
@@ -151,8 +225,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 +386,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 +409,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 +420,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 +472,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 +494,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 +522,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 +556,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}`;
@@ -440,6 +654,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"),
     }),
@@ -515,12 +771,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)."),
+        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). The second id MUST be a ROLE or CIRCLE nest. Never the project, task or tension you are commenting on: the mention renders that nest's title where the role name belongs, so a project id produces 'Henk as Write a weekly blog post', which reads as though the project were his role. If you do not know which role the person is acting in, use `@{userId}` rather than substituting the nest you happen to be working on. Other forms: `@{userId}` (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."),
     }),
     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. 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). The second id MUST be a ROLE or CIRCLE nest. Never the project, task or tension you are commenting on: the mention renders that nest's title where the role name belongs, so a project id produces 'Henk as Write a weekly blog post', which reads as though the project were his role. If you do not know which role the person is acting in, use `@{userId}` rather than substituting the nest you happen to be working on. Other forms: `@{userId}` (no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)."),
         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 +838,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"),
@@ -842,20 +1099,70 @@ export const schemas = {
     listConnectors: z.object({
         workspaceId: z.string().describe("Workspace ID whose connector catalog to list"),
     }),
+    listConnectorTemplates: z.object({
+        workspaceId: z.string().describe("Workspace ID whose available connector templates to list"),
+    }),
     registerConnector: z.object({
+        templateId: z.string().optional().describe("Id of a template from nestr_list_connector_templates. Given this, everything else is filled in from the template and you should omit type/config/capabilities/exposure/authStrategy. ALWAYS prefer this over hand-registering a vendor the deployment already knows."),
         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"),
+        type: z.enum(["mcp", "cli", "api"]).optional().describe("Transport: 'mcp' (MCP server over a url), 'api' (REST endpoint over a url), or 'cli' (a command). Required unless templateId is given."),
+        name: z.string().optional().describe("Unique connector name within the workspace catalog. Required unless templateId is given, where it defaults to the template's own name."),
         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."),
     }),
+    createAgent: z.object({
+        workspaceId: z.string().describe("Workspace ID to create the agent in"),
+        name: z.string().describe("The AGENT's own name, as its identity calls it (e.g. 'Collab'). Not the name of the work: that belongs to the role this agent will fill."),
+        agentConfig: coerceFromJson(z.record(z.unknown())).optional().describe("Runtime wiring, not persona: { runtimeCallbackUrl (https, or http to a *.svc.cluster.local service), tokenTtlSeconds (30-1800) }. Omit for an agent that runs on Nestr's own runtime."),
+    }),
     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."),
-        ownerId: z.string().describe("Owner ID. user/agent: the user ID. workspace: the workspace ID. role-domain: the domain nest ID."),
+        ownerType: z.enum(["role", "role-domain", "workspace"]).describe("Who gets access. 'role' is usually what you want: pass a role nest ID and the connector's domain is found or created under it. 'role-domain' targets an existing domain directly. 'workspace' gives everyone. Personal owners ('user', 'agent') are deliberately not available here: see the tool description."),
+        ownerId: z.string().describe("Owner ID. role: the role nest ID. role-domain: the domain nest ID. workspace: the workspace ID."),
+    }),
+    updateConnector: z.object({
+        workspaceId: z.string().describe("Workspace ID the connector belongs to"),
+        connectorId: z.string().describe("ID of the connector to update"),
+        type: z.enum(["mcp", "cli", "api"]).optional().describe("Transport"),
+        name: z.string().optional().describe("Unique connector name within the workspace catalog"),
+        config: coerceFromJson(z.record(z.unknown())).optional().describe("Per-type transport config, no secret"),
+        capabilities: coerceFromJson(z.record(z.unknown())).optional().describe("Capability descriptor"),
+        exposure: coerceFromJson(z.record(z.unknown())).optional().describe("Exposure policy: { userAgent, domainGated }"),
+        authStrategy: z.enum(["secret", "oauth2"]).optional().describe("How a principal connects"),
+        enabled: z.boolean().optional().describe("Switch the connector on or off in this workspace"),
+    }),
+    removeConnector: z.object({
+        workspaceId: z.string().describe("Workspace ID the connector belongs to"),
+        connectorId: z.string().describe("ID of the connector to remove from the catalog"),
+    }),
+    listConnections: z.object({
+        workspaceId: z.string().describe("Workspace ID whose bindings to list"),
+        includeDisabled: z.boolean().optional().describe("Include removed (disabled) bindings. Default false."),
+    }),
+    removeConnection: z.object({
+        workspaceId: z.string().describe("Workspace ID the binding belongs to"),
+        connectionId: z.string().describe("ID of the binding to remove, from nestr_list_connections"),
+    }),
+    getConnectLink: z.object({
+        workspaceId: z.string().describe("Workspace ID the binding belongs to"),
+        connectionId: z.string().describe("ID of the binding to connect, from nestr_list_connections"),
+    }),
+    revokeConnectionCredential: z.object({
+        workspaceId: z.string().describe("Workspace ID the binding belongs to"),
+        connectionId: z.string().describe("ID of the binding whose credential to revoke"),
+    }),
+    getAgentConnectorReach: z.object({
+        workspaceId: z.string().describe("Workspace ID the agent belongs to"),
+        agentUserId: z.string().describe("The agent's bot user ID"),
+    }),
+    runAgent: z.object({
+        workspaceId: z.string().describe("Workspace ID the agent belongs to"),
+        agentUserId: z.string().describe("The agent's bot user ID"),
+        nestId: z.string().describe("The nest the run is pinned to: a role, a project, a task"),
+        message: z.string().optional().describe("What this run is for. Omit for a plain 'advance this item' run."),
     }),
     // File attachments (a comment id works as the nestId — files are keyed by nestId)
     getNestFiles: z.object({
@@ -1161,12 +1468,12 @@ 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. 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; the second id must be a role or circle nest, never the project or task being commented on. Use for progress updates and discussion. Optionally attach labels at creation time via the `labels` parameter.",
         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)." },
+                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). The second id MUST be a ROLE or CIRCLE nest. Never the project, task or tension you are commenting on: the mention renders that nest's title where the role name belongs, so a project id produces 'Henk as Write a weekly blog post', which reads as though the project were his role. If you do not know which role the person is acting in, use `@{userId}` rather than substituting the nest you happen to be working on. Other forms: `@{userId}` (no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)." },
                 labels: {
                     type: "array",
                     items: { type: "string" },
@@ -1184,7 +1491,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. 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). The second id MUST be a ROLE or CIRCLE nest. Never the project, task or tension you are commenting on: the mention renders that nest's title where the role name belongs, so a project id produces 'Henk as Write a weekly blog post', which reads as though the project were his role. If you do not know which role the person is acting in, use `@{userId}` rather than substituting the nest you happen to be working on. Other forms: `@{userId}` (no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)." },
                 labels: {
                     type: "array",
                     items: { type: "string" },
@@ -1268,6 +1575,140 @@ export const toolDefinitions = [
         },
         ...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').",
@@ -1347,7 +1788,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: {
@@ -1390,7 +1831,10 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_workspace_user",
-        description: "Add a user to a workspace by email. Creates account if needed.",
+        description: "Add a user to a workspace by email. Creates the account if it does not exist, adds them, "
+            + "and SENDS THEM AN INVITE EMAIL, so confirm with the person asking before you call it: a real "
+            + "person receives that mail. This is the action behind requests about seats, membership, "
+            + "extending a plan by a person, or getting a colleague in.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2055,19 +2499,38 @@ export const toolDefinitions = [
         },
         ...readOnly,
     },
+    {
+        name: "nestr_list_connector_templates",
+        description: "The connector templates this deployment can add in one click, filtered to the ones it can actually offer. Each carries the vendor's real endpoint, transport, auth strategy and the deployment's OAuth client.\n\nCALL THIS FIRST, before nestr_register_connector, whenever the tool is a known vendor (Xero, HubSpot, Slack, Stripe, GitHub, Notion, Linear and so on). Hand-registering means guessing an endpoint, and a wrong guess authorises cleanly and then fails every call: a Xero connector registered against api.xero.com instead of the template's mcp.xero.com looked healthy in every record and returned 403 forever. Pass the id you find here as templateId to nestr_register_connector. Workspace-admin only.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID whose available connector templates to list" },
+            },
+            required: ["workspaceId"],
+        },
+        ...readOnly,
+    },
     {
         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. PREFER A TEMPLATE: call nestr_list_connector_templates first and pass its id as templateId, which fills in the vendor's real endpoint, transport, auth strategy and this deployment's OAuth client. Hand-registering a known vendor means guessing an endpoint, and a wrong guess authorises cleanly and then fails every call. Only describe the transport yourself for something the deployment has no template for. 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 (create one under the role with nestr_create_nest and labels ['circleplus-domain'] if the role has none yet: the bind refuses a role id), 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.",
         inputSchema: {
             type: "object",
             properties: {
+                templateId: {
+                    type: "string",
+                    description: "Id of a template from nestr_list_connector_templates. Given this, everything else is filled in from the template and you should omit type/config/capabilities/exposure/authStrategy. ALWAYS prefer this over hand-registering a vendor the deployment already knows.",
+                },
                 workspaceId: { type: "string", description: "Workspace ID to register the connector in" },
                 type: {
                     type: "string",
                     enum: ["mcp", "cli", "api"],
-                    description: "Transport: 'mcp' (MCP server over a url), 'api' (REST endpoint over a url), or 'cli' (a command)",
+                    description: "Transport: 'mcp' (MCP server over a url), 'api' (REST endpoint over a url), or 'cli' (a command). Required unless templateId is given.",
+                },
+                name: {
+                    type: "string",
+                    description: "Unique connector name within the workspace catalog. Required unless templateId is given, where it defaults to the template's own name.",
                 },
-                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.",
@@ -2086,13 +2549,36 @@ export const toolDefinitions = [
                     description: "How a principal connects: 'secret' (a one-time secret captured via the Connect button) or 'oauth2'. The agent never sees the secret.",
                 },
             },
-            required: ["workspaceId", "type", "name"],
+            // workspaceId only: with a templateId the transport comes from the template,
+            // and demanding type and name here is what made the whole template path
+            // unreachable from a client that reads the schema.
+            required: ["workspaceId"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_create_agent",
+        description: "Create an agent user in the workspace. Workspace-admin only; a non-admin caller gets AUTH_SCOPE_INSUFFICIENT (call nestr_diagnose on any auth error). The agent is added to the workspace and can then fill roles like a person does.\n\nAn agent and the role it fills are two different things, named differently: the agent carries its own name (Collab), the role is named for the WORK (Marketing). Do not name the role after the agent. Create the agent here, create or find the role with nestr_create_nest, then assign the agent to the role with nestr_update_nest users. Keeping them apart is what lets the agent be replaced without the role losing its purpose, accountabilities and history, and lets one agent fill several roles.\n\nThe agent's instructions do not go here: they belong in a skill nest under the role, which loads whenever the role acts. agentConfig is runtime wiring only.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID to create the agent in" },
+                name: {
+                    type: "string",
+                    description: "The AGENT's own name, as its identity calls it (e.g. 'Collab'). Not the name of the work: that belongs to the role this agent will fill.",
+                },
+                agentConfig: {
+                    type: "object",
+                    description: "Runtime wiring, not persona: { runtimeCallbackUrl (https, or http to a *.svc.cluster.local service), tokenTtlSeconds (30-1800) }. Omit for an agent that runs on Nestr's own runtime.",
+                },
+            },
+            required: ["workspaceId", "name"],
         },
         ...mutating,
     },
     {
         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: 'role' (ownerId is the role nest ID — the server finds or creates the connector's domain under it), 'role-domain' (ownerId is an existing domain nest ID), or 'workspace' (ownerId is the workspace ID). A 'role' or 'role-domain' owner 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.\n\nBIND TO THE ROLE, not to whoever fills it. A role binding is the governance act: the access belongs to the work, survives the filler changing, and is visible to the circle. Reach for 'role' by default — it is the usual onboarding path: pass the role nest ID and the server does the domain lookup. Use 'role-domain' only when you already have the domain nest ID and want to target it directly.\n\nPersonal owners ('user' and 'agent') are deliberately unavailable through this tool. They are for things that are genuinely one person's or one bot's, an individual mailbox being the usual case, and handing one agent the power to attach a credential to ANOTHER agent is not a decision to make from a tool call. When a personal binding is really what is wanted, say so and let a workspace admin set it up in the agent's own panel in the UI.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2100,21 +2586,132 @@ export const toolDefinitions = [
                 connectorId: { type: "string", description: "ID of an enabled connector from nestr_list_connectors" },
                 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.",
+                    enum: ["role", "workspace", "role-domain"],
+                    description: "Owner type. 'role' is the usual path: pass the role nest ID and the server finds or creates the connector's domain under it. 'role-domain' targets an existing domain directly. 'workspace' gives everyone. Personal owners ('user', 'agent') are deliberately not available here.",
                 },
                 ownerId: {
                     type: "string",
-                    description: "Owner ID. user/agent: the user ID. workspace: the workspace ID. role-domain: the domain nest ID.",
+                    description: "Owner ID. role: the role nest ID. role-domain: the domain nest ID. workspace: the workspace ID.",
                 },
             },
             required: ["workspaceId", "connectorId", "ownerType", "ownerId"],
         },
         ...mutating,
     },
+    {
+        name: "nestr_update_connector",
+        description: "Update a connector in the workspace catalog, or switch it on and off with `enabled`. Workspace-admin only. Switching it off, or narrowing its exposure, takes effect immediately everywhere it is used: the policy is re-read every time a credential is handed out, not only when access was given.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID the connector belongs to" },
+                connectorId: { type: "string", description: "ID of the connector to update" },
+                type: { type: "string", enum: ["mcp", "cli", "api"], description: "Transport" },
+                name: { type: "string", description: "Unique connector name within the workspace catalog" },
+                config: { type: "object", description: "Per-type transport config, no secret" },
+                capabilities: { type: "object", description: "Capability descriptor" },
+                exposure: { type: "object", description: "Exposure policy: { userAgent, domainGated }" },
+                authStrategy: { type: "string", enum: ["secret", "oauth2"], description: "How a principal connects" },
+                enabled: { type: "boolean", description: "Switch the connector on or off in this workspace" },
+            },
+            required: ["workspaceId", "connectorId"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_remove_connector",
+        description: "Remove a connector from the workspace catalog. Workspace-admin only. Bindings that named it stop resolving, so prefer nestr_update_connector with enabled:false when you only want to pause it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID the connector belongs to" },
+                connectorId: { type: "string", description: "ID of the connector to remove" },
+            },
+            required: ["workspaceId", "connectorId"],
+        },
+        ...destructive,
+    },
+    {
+        name: "nestr_list_connections",
+        description: "List who has access to what in this workspace: each binding's connector, its owner (a role's domain, a person, an agent, or the whole workspace), and who holds a credential on it. Shows when an agent is using a person's account, and never returns a secret. Use it to check whether access already exists before giving more, and to find the connectionId for nestr_get_connect_link.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID whose bindings to list" },
+                includeDisabled: { type: "boolean", description: "Include removed bindings. Default false." },
+            },
+            required: ["workspaceId"],
+        },
+    },
+    {
+        name: "nestr_remove_connection",
+        description: "Take a connector off an owner: the binding is removed and every credential on it revoked. Workspace-admin only. A domain left holding nothing goes back to being an ordinary descriptive domain.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID the binding belongs to" },
+                connectionId: { type: "string", description: "Binding ID from nestr_list_connections" },
+            },
+            required: ["workspaceId", "connectionId"],
+        },
+        ...destructive,
+    },
+    {
+        name: "nestr_get_connect_link",
+        description: "Get a link a PERSON opens to connect an account for a binding. This is how you finish setting up access: you can register a connector and give a role access, but you must never handle a raw token, so the sign-in or key entry happens behind this link. The link carries no authority — whoever opens it is checked then. Give it to the user in your reply.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID the binding belongs to" },
+                connectionId: { type: "string", description: "Binding ID from nestr_list_connections" },
+            },
+            required: ["workspaceId", "connectionId"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_revoke_connection_credential",
+        description: "Revoke the calling user's credential on a binding. The binding stays, so access can be restored by connecting again. Use nestr_remove_connection to remove the access entirely.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID the binding belongs to" },
+                connectionId: { type: "string", description: "Binding ID from nestr_list_connections" },
+            },
+            required: ["workspaceId", "connectionId"],
+        },
+        ...destructive,
+    },
+    {
+        name: "nestr_get_agent_connectors",
+        description: "What an agent can and cannot use, and why. Groups each connector by where the grant comes from (its own binding, the workspace, or a role it fills) and, when unavailable, names the reason: no credential yet, the connector is disabled, it has no usable tools, or it no longer allows this kind of access. Reach for this when an agent seems to be missing something it should have.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID the agent belongs to" },
+                agentUserId: { type: "string", description: "The agent's bot user ID" },
+            },
+            required: ["workspaceId", "agentUserId"],
+        },
+    },
+    {
+        name: "nestr_run_agent",
+        description: "Run an agent now on a nest, optionally saying what the run is for. This is how one agent asks another to do something. The run is pinned to the nest you name and reports back there. You need assign rights on that nest and the agent must fill or be assigned to it, so this cannot run an agent anywhere in the workspace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID the agent belongs to" },
+                agentUserId: { type: "string", description: "The agent's bot user ID" },
+                nestId: { type: "string", description: "The nest the run is pinned to: a role, a project, a task" },
+                message: { type: "string", description: "What this run is for. Omit for a plain 'advance this item' run." },
+            },
+            required: ["workspaceId", "agentUserId", "nestId"],
+        },
+        ...mutating,
+    },
     {
         name: "nestr_get_nest_files",
-        description: "List a nest's file attachments. A comment ID works too — files are keyed by nestId, so pass a comment ID to see files attached to that comment. Returns each file's id, name, contentType and size. Use nestr_read_file with a returned id to read one (images come back as viewable image content). Auth: any valid token with access to the nest.",
+        description: "List a nest's file attachments. Images pasted into the nest's text are deliberately excluded — they belong to the text that references them; the inline_images hint counts those and their ids come from the references in the content. A comment ID works too — files are keyed by nestId, so pass a comment ID to see files attached to that comment. Returns each file's id, name, contentType and size. Use nestr_read_file with a returned id to read one (images come back as viewable image content). Auth: any valid token with access to the nest.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2126,7 +2723,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_read_file",
-        description: "Read a single file attachment on a nest (or comment). Branches on contentType: images (image/*) return as viewable image content so you can see them (very large images return metadata only); JSON and text (application/json, text/*) return as decoded UTF-8 text (large text is truncated); PDFs and other types return their metadata only (cannot be inlined yet). Get file ids from nestr_get_nest_files. A comment ID works as the nestId. Auth: any valid token with access to the nest.",
+        description: "Read a single file attachment on a nest (or comment). Branches on contentType: images (image/*) return as viewable image content so you can see them (very large images return metadata only); JSON and text (application/json, text/*) return as decoded UTF-8 text (large text is truncated); PDFs and other types return their metadata only (cannot be inlined yet). Get file ids from nestr_get_nest_files, or, for an image pasted into a nest's text, from the ![name](/file/download?id=FILE_ID&name=NAME) reference in its content — those are not listed by nestr_get_nest_files but are readable here. A comment ID works as the nestId. Auth: any valid token with access to the nest.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2306,7 +2903,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 +3329,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 +3431,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);
@@ -3152,9 +3839,46 @@ async function _handleToolCall(client, name, args, context) {
                 const connectors = await client.listConnectors(parsed.workspaceId);
                 return formatResult(connectors);
             }
+            case "nestr_list_connector_templates": {
+                const parsed = schemas.listConnectorTemplates.parse(args);
+                const listed = await client.listConnectorTemplates(parsed.workspaceId);
+                const templates = listed.templates;
+                if (!Array.isArray(templates) || templates.length === 0) {
+                    return { content: [{ type: "text", text: "This deployment offers no connector templates." }] };
+                }
+                // Enriched so the hint arrives as the register call itself, pre-filled
+                // with the template id, the same treatment every other hint gets.
+                const enrichedTemplates = enrichHints({
+                    workspaceId: parsed.workspaceId,
+                    ...(listed.hints ? { hints: listed.hints } : {}),
+                });
+                return formatResult({
+                    message: "Pass the id of the one you want as templateId to nestr_register_connector. It carries the vendor's endpoint, transport and auth strategy, so nothing has to be guessed. Do not rebuild one of these by hand: a hand-built copy has no OAuth client and fails at first use.",
+                    templates,
+                    ...(enrichedTemplates.hints ? { hints: enrichedTemplates.hints } : {}),
+                });
+            }
             case "nestr_register_connector": {
                 const parsed = schemas.registerConnector.parse(args);
-                const connector = await client.registerConnector(parsed.workspaceId, {
+                if (parsed.templateId) {
+                    const fromTemplate = await client.registerConnector(parsed.workspaceId, {
+                        templateId: parsed.templateId,
+                        ...(parsed.name ? { name: parsed.name } : {}),
+                    });
+                    return formatResult({
+                        message: "Connector registered from a template, so its endpoint and auth strategy are the vendor's own. Next, bind it to a role's DOMAIN with nestr_bind_connector, then a human connects the account via the Connect button.",
+                        connector: fromTemplate.connector,
+                    });
+                }
+                if (!parsed.type || !parsed.name) {
+                    return formatError({
+                        error: true,
+                        code: "VALIDATION",
+                        message: "Without templateId, both type and name are required. Call nestr_list_connector_templates first: a known vendor almost always has one.",
+                        retryable: false,
+                    });
+                }
+                const registered = await client.registerConnector(parsed.workspaceId, {
                     type: parsed.type,
                     name: parsed.name,
                     config: parsed.config,
@@ -3162,9 +3886,27 @@ async function _handleToolCall(client, name, args, context) {
                     exposure: parsed.exposure,
                     authStrategy: parsed.authStrategy,
                 });
+                // Enriched so a template hint arrives as a tool call the model can make,
+                // the same treatment every other hint gets. workspaceId is on the entry,
+                // which is what lets enrichHints work on something that is not a nest.
+                const enriched = enrichHints({
+                    ...registered.connector,
+                    ...(registered.hints ? { hints: registered.hints } : {}),
+                });
+                return formatResult({
+                    message: "Connector registered. It does nothing yet: nobody has access to it. Give a ROLE access with nestr_bind_connector { ownerType: 'role', ownerId: <role nest id> } and its domain is created under that role, which is the usual onboarding path. Then get a link with nestr_get_connect_link and give it to a person to open, since the credential must never pass through you.",
+                    connector: enriched,
+                });
+            }
+            case "nestr_create_agent": {
+                const parsed = schemas.createAgent.parse(args);
+                const agent = await client.createAgent(parsed.workspaceId, {
+                    name: parsed.name,
+                    agentConfig: parsed.agentConfig,
+                });
                 return formatResult({
-                    message: "Connector registered. Next, bind it to an owner with nestr_bind_connector (e.g. a role's domain), then a human or agent connects the account via the credentials field's Connect button.",
-                    connector,
+                    message: "Agent created. Next, give it work to fill: create or find a role named for the WORK (not for the agent) with nestr_create_nest, then assign this agent to it with nestr_update_nest users. Its instructions belong in a skill nest under that role, not on the agent.",
+                    agent,
                 });
             }
             case "nestr_bind_connector": {
@@ -3173,14 +3915,75 @@ async function _handleToolCall(client, name, args, context) {
                     connectorId: parsed.connectorId,
                     owner: { type: parsed.ownerType, id: parsed.ownerId },
                 });
-                // For a role-domain binding the API materialises a credentials field on
-                // the domain; surface that explicitly so the caller knows the Connect
-                // button now renders there and the secret is captured out-of-band.
-                const message = parsed.ownerType === "role-domain"
-                    ? "Connector bound to the role's domain. A credentials field was materialised on the domain (see credentialsField) so the role can use the connector and the Connect button renders. A human or agent now connects the account via that button; the secret is captured out-of-band and never by the agent."
-                    : "Connector bound to the owner. The owner now connects the account out-of-band; the secret is never seen by the agent.";
+                // A role binding creates the connector's domain when there isn't one, so
+                // say where the access landed. The credential is always a separate,
+                // out-of-band step: hand the human a link from nestr_get_connect_link.
+                const message = parsed.ownerType === "role" || parsed.ownerType === "role-domain"
+                    ? "Access given to the role's domain. Nobody can use it until an account is connected: get a link with nestr_get_connect_link and give it to a person to open. The secret is captured out-of-band and never by the agent."
+                    : "Access given to the owner. Nobody can use it until an account is connected: get a link with nestr_get_connect_link and give it to a person to open. The secret is never seen by the agent.";
                 return formatResult({ message, connection });
             }
+            case "nestr_update_connector": {
+                const parsed = schemas.updateConnector.parse(args);
+                const { workspaceId, connectorId, ...updates } = parsed;
+                const connector = await client.updateConnector(workspaceId, connectorId, updates);
+                return formatResult({ message: "Connector updated.", connector });
+            }
+            case "nestr_remove_connector": {
+                const parsed = schemas.removeConnector.parse(args);
+                await client.removeConnector(parsed.workspaceId, parsed.connectorId);
+                return formatResult({
+                    message: "Connector removed from the catalog. Bindings that named it stop resolving.",
+                    connectorId: parsed.connectorId,
+                });
+            }
+            case "nestr_list_connections": {
+                const parsed = schemas.listConnections.parse(args);
+                const connections = await client.listConnections(parsed.workspaceId, {
+                    includeDisabled: parsed.includeDisabled,
+                });
+                return formatResult(connections);
+            }
+            case "nestr_remove_connection": {
+                const parsed = schemas.removeConnection.parse(args);
+                const result = await client.removeConnection(parsed.workspaceId, parsed.connectionId);
+                return formatResult({
+                    message: `Access removed. ${result.revokedCount} credential(s) revoked.`,
+                    connectionId: parsed.connectionId,
+                });
+            }
+            case "nestr_get_connect_link": {
+                const parsed = schemas.getConnectLink.parse(args);
+                const link = await client.getConnectLink(parsed.workspaceId, parsed.connectionId);
+                return formatResult({
+                    message: "Give this link to a person to open. They complete the sign-in or paste the key there, so the secret never passes through you.",
+                    ...link,
+                });
+            }
+            case "nestr_revoke_connection_credential": {
+                const parsed = schemas.revokeConnectionCredential.parse(args);
+                await client.revokeConnectionCredential(parsed.workspaceId, parsed.connectionId);
+                return formatResult({
+                    message: "Credential revoked. The binding stays; connect again to restore access.",
+                    connectionId: parsed.connectionId,
+                });
+            }
+            case "nestr_get_agent_connectors": {
+                const parsed = schemas.getAgentConnectorReach.parse(args);
+                const reach = await client.getAgentConnectorReach(parsed.workspaceId, parsed.agentUserId);
+                return formatResult(reach);
+            }
+            case "nestr_run_agent": {
+                const parsed = schemas.runAgent.parse(args);
+                const result = await client.runAgent(parsed.workspaceId, parsed.agentUserId, {
+                    nestId: parsed.nestId,
+                    message: parsed.message,
+                });
+                return formatResult({
+                    message: "The agent was dispatched. It reports back on the item it was run on.",
+                    ...result,
+                });
+            }
             case "nestr_get_nest_files": {
                 const parsed = schemas.getNestFiles.parse(args);
                 const files = await client.getNestFiles(parsed.nestId);