@nestr/mcp 0.1.98 → 0.1.100

package/build/tools/index.js

@@ -169,46 +169,6 @@ 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)
@@ -645,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({
@@ -722,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({
@@ -742,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)"),
@@ -754,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' })"),
@@ -771,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). 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."),
+        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). 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)."),
+        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({
@@ -1000,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." }),
@@ -1017,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"),
@@ -1099,70 +1064,20 @@ 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"]).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."),
+        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("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(["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."),
+        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)
     getNestFiles: z.object({
@@ -1194,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,
@@ -1226,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,
@@ -1238,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"],
         },
@@ -1291,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"],
         },
@@ -1308,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"],
         },
@@ -1346,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"],
@@ -1357,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" },
@@ -1400,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",
@@ -1468,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; 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.",
+        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). 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)." },
+                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"],
@@ -1491,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). 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)." },
+                body: { type: "string", description: `Updated comment text. ${MENTION_DESC}` },
                 labels: {
                     type: "array",
                     items: { type: "string" },
@@ -1524,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"],
         },
@@ -1541,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"],
         },
@@ -1569,7 +1484,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"],
         },
@@ -1778,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"],
@@ -1810,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"],
         },
@@ -1831,10 +1746,16 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_workspace_user",
-        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.",
+        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: {
@@ -1896,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,
@@ -1922,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"],
         },
@@ -2038,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,
@@ -2284,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: {
@@ -2292,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"],
         },
@@ -2318,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"],
         },
@@ -2356,6 +2277,7 @@ export const toolDefinitions = [
             },
             required: ["nestId", "tensionId", "partId"],
         },
+        ...readOnly,
     },
     {
         name: "nestr_create_tension_part_child",
@@ -2499,86 +2421,44 @@ 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. 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.",
+        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: {
-                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). 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.",
+                    description: "Transport: 'mcp' (MCP server over a url), 'api' (REST endpoint over a url), or 'cli' (a command)",
                 },
+                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.",
                 },
             },
-            // 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"],
+            required: ["workspaceId", "type", "name"],
         },
         ...mutating,
     },
     {
         name: "nestr_bind_connector",
-        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.",
+        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: {
@@ -2586,129 +2466,18 @@ export const toolDefinitions = [
                 connectorId: { type: "string", description: "ID of an enabled connector from nestr_list_connectors" },
                 ownerType: {
                     type: "string",
-                    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.",
+                    enum: ["user", "agent", "workspace", "role-domain"],
+                    description: "Owner type. 'role-domain' binds to a role's domain, materialising a credentials field there.",
                 },
                 ownerId: {
                     type: "string",
-                    description: "Owner ID. role: the role nest ID. role-domain: the domain nest ID. workspace: the workspace ID.",
+                    description: "Owner ID. user/agent: the user ID. workspace: the workspace ID. role-domain: the domain nest 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. 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.",
@@ -2764,6 +2533,13 @@ export const toolDefinitions = [
         ...destructive,
     },
 ];
+// The read-only surface (/mcp/readonly) serves an authenticated bearer but only
+// tools that cannot change anything. Derived from the annotations rather than a
+// hand-kept list, so a new tool is denied until someone marks it readOnly: the
+// failure mode of forgetting is a missing capability, not a silent write.
+export const READONLY_TOOL_NAMES = new Set(toolDefinitions
+    .filter((t) => t.annotations?.readOnlyHint === true)
+    .map((t) => t.name));
 // Strip description fields from nest objects in response data
 export function stripDescriptionFields(data) {
     if (Array.isArray(data)) {
@@ -2889,6 +2665,18 @@ async function _handleToolCall(client, name, args, context) {
                 return formatResult(PUBLIC_GUEST_ME);
             }
         }
+        // READ-ONLY surface gate (defense in depth — the readonly route also filters
+        // the advertised tool list). Anything not marked readOnlyHint is refused,
+        // including tools carrying no annotation at all.
+        if (context?.isReadOnly && !READONLY_TOOL_NAMES.has(name)) {
+            return formatError({
+                error: true,
+                code: "AUTH_SCOPE_INSUFFICIENT",
+                message: `Tool '${name}' is not available on the read-only Nestr MCP. This workspace is out of AI credit, so the agent can read but not change anything.`,
+                retryable: false,
+                hint: "Add AI credit, or raise the monthly ceiling if that is what was reached, to restore the full toolset.",
+            });
+        }
         switch (name) {
             case "nestr_help": {
                 const parsed = schemas.help.parse(args);
@@ -3839,46 +3627,9 @@ 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);
-                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, {
+                const connector = await client.registerConnector(parsed.workspaceId, {
                     type: parsed.type,
                     name: parsed.name,
                     config: parsed.config,
@@ -3886,27 +3637,9 @@ 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: "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,
+                    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,
                 });
             }
             case "nestr_bind_connector": {
@@ -3915,75 +3648,14 @@ async function _handleToolCall(client, name, args, context) {
                     connectorId: parsed.connectorId,
                     owner: { type: parsed.ownerType, id: parsed.ownerId },
                 });
-                // 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.";
+                // 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.";
                 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);