@nestr/mcp 0.1.47 → 0.1.49

package/build/tools/index.js

@@ -27,7 +27,7 @@ function completableResponse(data, source, title) {
 // Fields to keep for compact list responses (reduces token usage)
 const COMPACT_FIELDS = {
     // Common fields for all nests (includes fields needed by the completable list app)
-    base: ["_id", "title", "purpose", "completed", "labels", "path", "parentId", "ancestors", "description", "due"],
+    base: ["_id", "title", "purpose", "completed", "labels", "path", "parentId", "ancestors", "description", "due", "hints"],
     // Additional fields for roles
     role: ["accountabilities", "domains"],
     // Additional fields for users
@@ -65,6 +65,85 @@ function compactResponse(data, type = "nest") {
         return compact;
     });
 }
+// URL-to-tool mapping for hint enrichment.
+// The Nestr API returns hints with relative URLs (e.g., "/nests/abc123/children?search=...").
+// This maps those URL patterns to MCP tool calls so models can act on hints directly.
+// Note: patterns are tried in order — more specific patterns must come before catch-alls.
+const HINT_URL_PATTERNS = [
+    // /nests/{id}/children?search=... → nestr_search with in:{id} scoped query
+    {
+        pattern: /^\/nests\/([^/]+)\/children$/,
+        tool: "nestr_search",
+        params: (m, sp, workspaceId) => {
+            const search = sp.get("search") || "";
+            const result = { query: `in:${m[1]} ${search}`.trim() };
+            if (workspaceId)
+                result.workspaceId = workspaceId;
+            return result;
+        },
+    },
+    // /nests/{id}/posts → nestr_get_comments
+    { pattern: /^\/nests\/([^/]+)\/posts$/, tool: "nestr_get_comments", params: (m) => ({ nestId: m[1] }) },
+    // /nests/{id}/tensions → nestr_list_tensions
+    { pattern: /^\/nests\/([^/]+)\/tensions$/, tool: "nestr_list_tensions", params: (m) => ({ nestId: m[1] }) },
+    // /nests/{id} → nestr_get_nest (must be last — catches all /nests/{id} patterns)
+    { pattern: /^\/nests\/([^/]+)$/, tool: "nestr_get_nest", params: (m) => ({ nestId: m[1] }) },
+];
+// Enrich hints with tool call parameters so models can act on hints directly.
+// Extracts workspaceId from nest ancestors (last element) for search-based hints.
+function enrichHints(data) {
+    if (!data || typeof data !== "object")
+        return data;
+    // Handle arrays (e.g., from getNestChildren)
+    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) };
+    }
+    // Enrich hints on this nest
+    const record = data;
+    if (Array.isArray(record.hints)) {
+        // Extract workspaceId from ancestors (last element is always the workspace)
+        const ancestors = record.ancestors;
+        const workspaceId = ancestors?.length ? ancestors[ancestors.length - 1] : undefined;
+        record.hints = record.hints.map((hint) => {
+            if (!hint.url)
+                return hint;
+            // Parse URL and query params — strip absolute URL prefix if present
+            let rawUrl = hint.url;
+            const apiPrefixMatch = rawUrl.match(/^https?:\/\/[^/]+\/api(\/.*)/);
+            if (apiPrefixMatch)
+                rawUrl = apiPrefixMatch[1];
+            const [path, queryString] = rawUrl.split("?");
+            const searchParams = new URLSearchParams(queryString || "");
+            for (const { pattern, tool, params } of HINT_URL_PATTERNS) {
+                const match = path.match(pattern);
+                if (match) {
+                    return { ...hint, toolCall: { tool, params: params(match, searchParams, workspaceId) } };
+                }
+            }
+            // Log unrecognized hint URLs so we can add mappings when the API adds new patterns
+            console.error(`[nestr-mcp] Unrecognized hint URL pattern: "${hint.url}" (hint type: ${hint.type})`);
+            return hint;
+        });
+    }
+    return data;
+}
+// Coerce JSON-stringified arrays/objects before Zod validation.
+// Some MCP clients send array/object params as JSON strings (e.g., "[\"project\"]" instead of ["project"]).
+const coerceFromJson = (schema) => z.preprocess((val) => {
+    if (typeof val === 'string') {
+        try {
+            return JSON.parse(val);
+        }
+        catch {
+            return val;
+        }
+    }
+    return val;
+}, schema);
 // Tool input schemas using Zod
 export const schemas = {
     listWorkspaces: z.object({
@@ -81,7 +160,7 @@ export const schemas = {
         type: z.enum(['personal', 'collaborative']).optional().describe("'personal' for individual use (free forever), 'collaborative' for team use (free trial, then paid). Defaults to 'collaborative'."),
         governance: z.enum(['holacracy', 'sociocracy', 'roles_circles']).optional().describe("Self-organization model. Defaults to 'roles_circles' (generic role-based)."),
         plan: z.enum(['starter', 'pro']).optional().describe("Subscription plan for collaborative workspaces. Defaults to 'pro' (17-day trial)."),
-        apps: z.array(z.enum(['okr', 'feedback', 'insights'])).optional().describe("Apps to enable (e.g., ['okr', 'feedback']). 'insights' requires pro plan."),
+        apps: coerceFromJson(z.array(z.enum(['okr', 'feedback', 'insights']))).optional().describe("Apps to enable (e.g., ['okr', 'feedback']). 'insights' requires pro plan."),
         layout: z.enum(['board', 'list']).optional().describe("Layout style for personal workspaces. 'board' creates kanban columns (Todo, Doing, Done)."),
     }),
     search: z.object({
@@ -108,10 +187,10 @@ export const schemas = {
         title: z.string().describe("Title of the new nest (plain text, HTML stripped)"),
         purpose: z.string().optional().describe("Purpose — the aspirational future state this nest is working towards. Most important for workspaces, circles, and roles where it defines the north star and context boundary. For other nests, prefer description or fields for detailed information — but purpose can be set if meaningful. Supports HTML."),
         description: z.string().optional().describe("Detailed description — the primary field for storing information about a nest. Use for project details, task context, acceptance criteria, Definition of Done, etc. Supports HTML: <b>, <i>, <code>, <ul>, <li>, <a>."),
-        labels: z.array(z.string()).optional().describe("Label IDs to apply"),
-        users: z.array(z.string()).optional().describe("User IDs to assign (required for tasks/projects to associate with a person)"),
-        accountabilities: z.array(z.string()).optional().describe("Accountability titles for roles/circles. Only used when labels include 'role' or 'circle'. Each string becomes an accountability child nest."),
-        domains: z.array(z.string()).optional().describe("Domain titles for roles/circles. Only used when labels include 'role' or 'circle'. Each string becomes a domain child nest."),
+        labels: coerceFromJson(z.array(z.string())).optional().describe("Label IDs to apply"),
+        users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign (required for tasks/projects to associate with a person)"),
+        accountabilities: coerceFromJson(z.array(z.string())).optional().describe("Accountability titles for roles/circles. Only used when labels include 'role' or 'circle'. Each string becomes an accountability child nest."),
+        domains: coerceFromJson(z.array(z.string())).optional().describe("Domain titles for roles/circles. Only used when labels include 'role' or 'circle'. Each string becomes a domain child nest."),
         workspaceId: z.string().optional().describe("Workspace ID. Required when creating roles/circles with accountabilities or domains (used to route to the self-organization API)."),
     }),
     updateNest: z.object({
@@ -120,14 +199,14 @@ export const schemas = {
         purpose: z.string().optional().describe("New purpose — the aspirational future state. Most important for workspaces, circles, and roles. For other nests, prefer description or fields — but purpose can be set if meaningful. Supports HTML."),
         description: z.string().optional().describe("New description — the primary field for detailed information. Use for project details, task context, acceptance criteria, etc. Supports HTML."),
         parentId: z.string().optional().describe("New parent ID (move nest to different location, e.g., move inbox item to a role or project)"),
-        labels: z.array(z.string()).optional().describe("Label IDs to set (e.g., ['project'] to convert an item into a project)"),
-        fields: z.record(z.unknown()).optional().describe("Field updates (e.g., { 'project.status': 'Current' })"),
-        users: z.array(z.string()).optional().describe("User IDs to assign"),
-        data: z.record(z.unknown()).optional().describe("Key-value data store shared with Nestr internals — never overwrite existing keys. Namespace your own data under 'mcp.' (e.g., { 'mcp.lastSync': '...' }). For AI knowledge persistence, use skills instead."),
+        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' })"),
+        users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign"),
+        data: coerceFromJson(z.record(z.unknown())).optional().describe("Key-value data store shared with Nestr internals — never overwrite existing keys. Namespace your own data under 'mcp.' (e.g., { 'mcp.lastSync': '...' }). For AI knowledge persistence, use skills instead."),
         due: z.string().optional().describe("Due date (ISO format). For projects/tasks: deadline. For roles: re-election date. For meetings: start time."),
         completed: z.boolean().optional().describe("Mark task as completed (root-level field, not in fields). Note: Projects use fields['project.status'] = 'Done' instead."),
-        accountabilities: z.array(z.string()).optional().describe("Accountability titles for roles/circles (replaces existing). Only used when updating a role or circle. Requires workspaceId."),
-        domains: z.array(z.string()).optional().describe("Domain titles for roles/circles (replaces existing). Only used when updating a role or circle. Requires workspaceId."),
+        accountabilities: coerceFromJson(z.array(z.string())).optional().describe("Accountability titles for roles/circles (replaces existing). Only used when updating a role or circle. Requires workspaceId."),
+        domains: coerceFromJson(z.array(z.string())).optional().describe("Domain titles for roles/circles (replaces existing). Only used when updating a role or circle. Requires workspaceId."),
         workspaceId: z.string().optional().describe("Workspace ID. Required when updating accountabilities or domains on roles/circles."),
     }),
     deleteNest: z.object({
@@ -135,11 +214,11 @@ 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)"),
+        body: z.string().describe("Comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})"),
     }),
     updateComment: z.object({
         commentId: z.string().describe("Comment ID to update"),
-        body: z.string().describe("Updated comment text (supports HTML and @mentions)"),
+        body: z.string().describe("Updated comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})"),
     }),
     deleteComment: z.object({
         commentId: z.string().describe("Comment ID to delete"),
@@ -216,7 +295,7 @@ export const schemas = {
     }),
     // Inbox tools (require OAuth token)
     listInbox: z.object({
-        completedAfter: z.string().optional().describe("Include completed items from this date (ISO format). If omitted, only non-completed items are returned."),
+        completedAfter: z.string().optional().describe("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."),
     }),
     createInboxItem: z.object({
         title: z.string().describe("Title of the inbox item (plain text, HTML stripped)"),
@@ -230,10 +309,10 @@ export const schemas = {
         title: z.string().optional().describe("Updated title (plain text, HTML stripped)"),
         description: z.string().optional().describe("Updated description (supports HTML)"),
         completed: z.boolean().optional().describe("Mark as completed (processed)"),
-        data: z.record(z.unknown()).optional().describe("Custom data storage"),
+        data: coerceFromJson(z.record(z.unknown())).optional().describe("Custom data storage"),
     }),
     reorderInbox: z.object({
-        nestIds: z.array(z.string()).describe("Array of inbox item IDs in the desired order"),
+        nestIds: coerceFromJson(z.array(z.string())).describe("Array of inbox item IDs in the desired order"),
     }),
     reorderInboxItem: z.object({
         nestId: z.string().describe("ID of the inbox item to reorder"),
@@ -250,10 +329,10 @@ export const schemas = {
         labelId: z.string().describe("Label ID to remove"),
     }),
     addToDailyPlan: z.object({
-        nestIds: z.array(z.string()).describe("Array of nest IDs to add to the daily plan"),
+        nestIds: coerceFromJson(z.array(z.string())).describe("Array of nest IDs to add to the daily plan"),
     }),
     removeFromDailyPlan: z.object({
-        nestIds: z.array(z.string()).describe("Array of nest IDs to remove from the daily plan"),
+        nestIds: coerceFromJson(z.array(z.string())).describe("Array of nest IDs to remove from the daily plan"),
     }),
     // Personal labels (require OAuth token)
     listPersonalLabels: z.object({}),
@@ -271,7 +350,7 @@ export const schemas = {
     }),
     bulkReorder: z.object({
         workspaceId: z.string().describe("Workspace ID"),
-        nestIds: z.array(z.string()).describe("Array of nest IDs in the desired order"),
+        nestIds: coerceFromJson(z.array(z.string())).describe("Array of nest IDs in the desired order"),
     }),
     // Daily plan (requires OAuth token)
     getDailyPlan: z.object({}),
@@ -334,14 +413,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: 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("Labels defining the item type (e.g., ['role'], ['circle'], ['policy'], ['accountability'], ['domain'])"),
         purpose: z.string().optional().describe("Purpose — aspirational future state. Most important for roles/circles where it defines the north star. Supports HTML."),
         description: z.string().optional().describe("Description — detailed information about the item. Supports HTML."),
         parentId: z.string().optional().describe("Parent ID — use to move/restructure items (e.g., move role to different circle)"),
-        users: z.array(z.string()).optional().describe("User IDs to assign (e.g., for role elections: assign the elected user to the role)"),
+        users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign (e.g., for role elections: assign the elected user to the role)"),
         due: z.string().optional().describe("Due date / re-election date (ISO format)"),
-        accountabilities: z.array(z.string()).optional().describe("Accountability titles to set on a role (replaces all — use children endpoint for individual management)"),
-        domains: z.array(z.string()).optional().describe("Domain titles to set on a role (replaces all — use children endpoint for individual management)"),
+        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)"),
     }),
     modifyTensionPart: z.object({
         nestId: z.string().describe("ID of the circle or role the tension belongs to"),
@@ -350,12 +429,12 @@ export const schemas = {
         title: z.string().optional().describe("Updated title"),
         purpose: z.string().optional().describe("Updated purpose — aspirational future state. Most important for roles/circles. Supports HTML."),
         description: z.string().optional().describe("Updated description — detailed information. Supports HTML."),
-        labels: z.array(z.string()).optional().describe("Updated labels"),
+        labels: coerceFromJson(z.array(z.string())).optional().describe("Updated labels"),
         parentId: z.string().optional().describe("Updated parent ID"),
-        users: z.array(z.string()).optional().describe("Updated user assignments"),
+        users: coerceFromJson(z.array(z.string())).optional().describe("Updated user assignments"),
         due: z.string().optional().describe("Updated due date (ISO format)"),
-        accountabilities: z.array(z.string()).optional().describe("Updated accountabilities (replaces all — use children endpoint for individual management)"),
-        domains: 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 — use children endpoint for individual management)"),
+        domains: coerceFromJson(z.array(z.string())).optional().describe("Updated domains (replaces all — use children endpoint for individual management)"),
     }),
     removeTensionPart: z.object({
         nestId: z.string().describe("ID of the circle or role the tension belongs to"),
@@ -372,7 +451,7 @@ export const schemas = {
         tensionId: z.string().describe("Tension ID"),
         partId: z.string().describe("Part ID"),
         title: z.string().describe("Title for the new accountability or domain"),
-        labels: z.array(z.string()).describe("Labels defining the type: ['accountability'] or ['domain']"),
+        labels: coerceFromJson(z.array(z.string())).describe("Labels defining the type: ['accountability'] or ['domain']"),
     }),
     updateTensionPartChild: z.object({
         nestId: z.string().describe("ID of the circle or role the tension belongs to"),
@@ -493,7 +572,27 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_search",
-        description: "Search for nests within a workspace. Supports operators: label:, parent-label:, assignee: (me/userId/!userId/none), admin:, createdby:, completed:, type:, has: (due/pastdue/children/incompletechildren), depth:, mindepth:, in:, updated-date:, limit:, template:, data.property:, fields.{label}.{property}: to search any value in a nest's fields object (supports partial match, e.g., fields.project.status:Current — use nestr_get_nest with fieldsMetaData=true to discover available fields), label->field:value. Use ! prefix for negation. IMPORTANT: Use completed:false when searching for work to exclude old completed items. Response includes meta.total showing total matching count. IMPORTANT UI RULE: The completable list app must ONLY be used when results contain completable items (tasks, projects, todos) AND there are results to show. When searching for roles, circles, metrics, policies, or any non-completable type, you MUST omit the _listTitle parameter and respond in plain text instead — never render these in the app. Also never render empty results in the app.",
+        description: `Search for nests within a workspace. IMPORTANT: Use completed:false when searching for work to exclude old completed items.
+
+Operators (combine with spaces for AND; commas within operator for OR; ! prefix for negation):
+- label:role / label:!project — Filter/exclude by label
+- parent-label:circle — Parent has this label
+- assignee:me / assignee:userId / assignee:none / assignee:!userId — Filter by assignee
+- completed:false / completed:true / completed:past_7_days / completed:this_month / completed:YYYY-MM-DD_YYYY-MM-DD
+- in:nestId — Scope to descendants of a specific nest
+- depth:1 / depth:2 — Limit depth (1=direct children, 2=children+grandchildren)
+- mindepth:N — Minimum depth from context
+- has:due / has:pastdue / has:children / has:incompletechildren (supports ! prefix)
+- project->status:Current,Future / project->status:!Done — Field value search (label->field:value)
+- fields.label.property:value — Search any field value (supports partial match)
+- data.property:value — Search data properties
+- updated-date:past_7_days / updated-date:!past_30_days — Filter by update recency
+- sort:title / sort:due / sort:updatedAt / sort:createdAt + sort-order:asc/desc
+- createdby:me / admin:me / type:comment / limit:N / template:id
+
+Examples: label:role → all roles | assignee:me completed:false → my active work | in:circleId label:role depth:1 → roles in circle | label:project project->status:Current → active projects | in:roleId label:project → role's projects | has:pastdue completed:false → overdue items | label:accountability customer → accountabilities matching keyword
+
+Response includes meta.total showing total matching count. IMPORTANT UI RULE: The completable list app must ONLY be used when results are confirmed to contain completable items (tasks, projects, todos) AND there are results to show. When searching for roles, circles, metrics, policies, or any non-completable type, you MUST omit the _listTitle parameter and respond in plain text instead. Never render empty results in the app.`,
         inputSchema: {
             type: "object",
             properties: {
@@ -506,7 +605,8 @@ export const toolDefinitions = [
             },
             required: ["workspaceId", "query"],
         },
-        _meta: completableListUi,
+        // No _meta: completableListUi — search returns all types of nests (roles, circles, etc.).
+        // The completable list app should only be used when results are confirmed to be completable items.
         ...readOnly,
     },
     {
@@ -539,12 +639,13 @@ export const toolDefinitions = [
             },
             required: ["nestId"],
         },
-        _meta: completableListUi,
+        // No _meta: completableListUi — children can be any type (roles, accountabilities, etc.).
+        // The completable list app should only be used when results are confirmed to be completable items.
         ...readOnly,
     },
     {
         name: "nestr_create_nest",
-        description: "Create a new nest (task, project, role, circle, etc.) under a parent. Set users to assign to people - placing under a role does NOT auto-assign. For roles and circles: include accountabilities and domains arrays to create them inline (requires workspaceId). The API auto-routes to the self-organization endpoint when governance labels are detected with accountabilities/domains.",
+        description: "Create a new nest (task, project, role, circle, etc.) under a parent. Set users to assign to people - placing under a role does NOT auto-assign. For roles and circles: include accountabilities and domains arrays to create them inline (requires workspaceId). The API auto-routes to the self-organization endpoint when governance labels are detected with accountabilities/domains. GOVERNANCE RULE: Only create roles, circles, accountabilities, domains, or policies directly during workspace/circle setup mode (new or sparsely populated workspace). In established workspaces with multiple users, governance changes MUST go through the tension/proposal flow (nestr_create_tension + nestr_add_tension_part) so circle members can consent.",
         inputSchema: {
             type: "object",
             properties: {
@@ -583,7 +684,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_update_nest",
-        description: "Update properties of an existing nest. Use parentId to move a nest (e.g., inbox item to a project). For roles and circles: include accountabilities and domains arrays to update them inline (requires workspaceId). For AI knowledge persistence, create skill-labeled nests under roles/circles instead of using data fields.",
+        description: "Update properties of an existing nest. Use parentId to move a nest (e.g., inbox item to a project). For roles and circles: include accountabilities and domains arrays to update them inline (requires workspaceId). For AI knowledge persistence, create skill-labeled nests under roles/circles instead of using data fields. GOVERNANCE RULE: Only modify governance items (roles, circles, accountabilities, domains, policies) directly during setup mode. In established workspaces, governance changes MUST go through tensions (nestr_create_tension + nestr_add_tension_part).",
         inputSchema: {
             type: "object",
             properties: {
@@ -639,7 +740,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_delete_nest",
-        description: "Delete a nest (use with caution)",
+        description: "Delete a nest (use with caution). GOVERNANCE RULE: To remove governance items (roles, accountabilities, domains, policies) in established workspaces, use nestr_remove_tension_part to propose deletion through the consent process instead.",
         inputSchema: {
             type: "object",
             properties: {
@@ -651,12 +752,12 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_comment",
-        description: "Add a comment to a nest. Use @username to mention someone.",
+        description: "Add a comment to a nest. Supports @mentions using the format @{userId|email|circle|everyone}: @{userId} mentions by user ID, @{email} mentions by any email the user is registered with in Nestr, @{circle} notifies all role fillers in the nearest ancestor circle, @{everyone} is available in the UI but not yet via the API.",
         inputSchema: {
             type: "object",
             properties: {
                 nestId: { type: "string", description: "Nest ID to comment on" },
-                body: { type: "string", description: "Comment text (supports HTML and @mentions)" },
+                body: { type: "string", description: "Comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})" },
             },
             required: ["nestId", "body"],
         },
@@ -664,12 +765,12 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_update_comment",
-        description: "Update an existing comment's text.",
+        description: "Update an existing comment's text. Supports @mentions using the format @{userId|email|circle|everyone}: @{userId} mentions by user ID, @{email} mentions by any email the user is registered with in Nestr, @{circle} notifies all role fillers in the nearest ancestor circle, @{everyone} is available in the UI but not yet via the API.",
         inputSchema: {
             type: "object",
             properties: {
                 commentId: { type: "string", description: "Comment ID to update" },
-                body: { type: "string", description: "Updated comment text (supports HTML and @mentions)" },
+                body: { type: "string", description: "Updated comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})" },
             },
             required: ["commentId", "body"],
         },
@@ -901,7 +1002,7 @@ export const toolDefinitions = [
         inputSchema: {
             type: "object",
             properties: {
-                completedAfter: { type: "string", description: "Include completed items from this date (ISO format). If omitted, only non-completed items are returned." },
+                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." },
             },
         },
@@ -952,7 +1053,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_reorder_inbox",
-        description: "Reorder inbox items by providing an array of item IDs in the desired order. You can provide a subset of items - they will be placed at the top in the given order, with remaining items unchanged below. Requires OAuth token.",
+        description: "Reorder inbox items by providing an array of item IDs in the desired order. You can provide a subset of items — they will be placed at the top in the given order, while all other items retain their existing order below them. To move non-completed items to the top, simply pass their IDs — there is no need to fetch completed items. Requires OAuth token.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1548,7 +1649,7 @@ async function _handleToolCall(client, name, args) {
                     fieldsMetaData: parsed.fieldsMetaData,
                     hints: parsed.hints !== false,
                 });
-                return formatResult(nest);
+                return formatResult(enrichHints(nest));
             }
             case "nestr_get_nest_children": {
                 const parsed = schemas.getNestChildren.parse(args);
@@ -1558,7 +1659,7 @@ async function _handleToolCall(client, name, args) {
                     cleanText: true,
                     hints: parsed.hints !== false,
                 });
-                return formatResult(completableResponse(compactResponse(children), "children", parsed._listTitle || "Sub-items"));
+                return formatResult(completableResponse(compactResponse(enrichHints(children)), "children", parsed._listTitle || "Sub-items"));
             }
             case "nestr_create_nest": {
                 const parsed = schemas.createNest.parse(args);