@intangle/mcp-server 2.5.4 → 2.5.6

package/.env.local

@@ -1,2 +1,3 @@
 MCP_API_KEY=mcp_placeholder_key_will_be_replaced_by_user_specific_key
 NEXT_APP_URL=https://intangle.app
+VERCEL_BYPASS_TOKEN=igXBygPO1T5dWLBaVyQiN9QB7IECZ50O

package/dist/index.js

@@ -7,7 +7,7 @@ import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ErrorCode, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { config } from "dotenv";
 import fetch from "node-fetch";
 import { TOOLS } from "./tool-definitions.js";
@@ -101,6 +101,13 @@ try {
         }
         return url.toString();
     }
+    function buildRemoteApiUrl() {
+        const url = new URL("/api/mcp-remote", API_BASE_URL);
+        if (VERCEL_BYPASS_TOKEN) {
+            url.searchParams.set("x-vercel-protection-bypass", VERCEL_BYPASS_TOKEN);
+        }
+        return url.toString();
+    }
     async function makeApiCall(endpoint, data, timeoutMs) {
         // Ensure we have client info before making requests
         ensureClientInfo();
@@ -160,6 +167,57 @@ try {
             clearTimeout(timeoutId);
         }
     }
+    async function makeRemoteRpcCall(method, params) {
+        ensureClientInfo();
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${MCP_API_KEY}`,
+            "User-Agent": mcpClientName
+                ? `${mcpClientName}/${mcpClientVersion || "unknown"} (mcp-stdio)`
+                : "MCP-Client-Stdio/1.1.2 (mcp)",
+        };
+        if (mcpClientName) {
+            headers["X-MCP-Client-Name"] = mcpClientName;
+        }
+        if (mcpClientVersion) {
+            headers["X-MCP-Client-Version"] = mcpClientVersion;
+        }
+        if (VERCEL_BYPASS_TOKEN) {
+            headers["x-vercel-protection-bypass"] = VERCEL_BYPASS_TOKEN;
+        }
+        const requestId = Date.now();
+        const rpcBody = {
+            jsonrpc: "2.0",
+            id: requestId,
+            method,
+            params,
+        };
+        const response = await fetch(buildRemoteApiUrl(), {
+            method: "POST",
+            headers,
+            body: JSON.stringify(rpcBody),
+        });
+        const responseText = await response.text();
+        let responseJson = {};
+        try {
+            responseJson = responseText ? JSON.parse(responseText) : {};
+        }
+        catch {
+            throw new Error(`Failed to parse MCP remote ${method} response`);
+        }
+        if (!response.ok) {
+            const message = responseJson?.error?.message ||
+                responseJson?.message ||
+                `${response.status} ${response.statusText}`;
+            throw new Error(`MCP remote ${method} failed: ${message}`);
+        }
+        if (responseJson?.error) {
+            const code = responseJson.error.code;
+            const message = responseJson.error.message || "Unknown MCP remote error";
+            throw new Error(`MCP remote ${method} error (${code}): ${message}`);
+        }
+        return responseJson?.result ?? {};
+    }
     const server = new Server({
         name: "intangle-context",
         version: "1.0.0",
@@ -171,12 +229,33 @@ try {
         ],
     }, {
         capabilities: {
+            resources: {},
             tools: {},
         },
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: TOOLS,
     }));
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const result = await makeRemoteRpcCall("resources/list", {});
+        return {
+            resources: Array.isArray(result?.resources) ? result.resources : [],
+            nextCursor: typeof result?.nextCursor === "string" ? result.nextCursor : undefined,
+        };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request?.params?.uri;
+        if (!uri || typeof uri !== "string") {
+            throw new McpError(ErrorCode.InvalidParams, "uri is required for resources/read");
+        }
+        const result = await makeRemoteRpcCall("resources/read", { uri });
+        return {
+            contents: Array.isArray(result?.contents) ? result.contents : [],
+        };
+    });
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+        resourceTemplates: [],
+    }));
     async function handleSearchContext(args) {
         const { space_id, query, topics } = args;
         // Require space_id
@@ -250,16 +329,39 @@ try {
             delete: args.delete,
         });
     }
+    async function handleUpdateFolders(args) {
+        if (!args.space_id) {
+            throw new Error("space_id is required. Use view_spaces to see available options.");
+        }
+        const hasOperation = !!args.list ||
+            (Array.isArray(args.create) && args.create.length > 0) ||
+            (Array.isArray(args.rename) && args.rename.length > 0) ||
+            (Array.isArray(args.move_items) && args.move_items.length > 0) ||
+            (Array.isArray(args.delete) && args.delete.length > 0);
+        if (!hasOperation) {
+            throw new Error("At least one operation is required: list, create, rename, move_items, or delete.");
+        }
+        return makeApiCall("update-folders", {
+            space_id: args.space_id,
+            list: args.list,
+            create: args.create,
+            rename: args.rename,
+            move_items: args.move_items,
+            delete: args.delete,
+        });
+    }
     async function handleMessage(args) {
         if (!args.space_id || !args.content) {
             throw new Error("space_id and content are required");
         }
+        // Keep one-turn MCP calls safely under common external tool-call deadlines
+        // while still allowing caller override for longer jobs.
         const timeoutMs = typeof args.timeout_ms === "number" && Number.isFinite(args.timeout_ms)
             ? Math.max(10_000, Math.min(300_000, Math.trunc(args.timeout_ms)))
-            : undefined;
+            : 100_000;
         // Give backend a little extra headroom beyond requested assistant timeout.
-        const requestTimeout = timeoutMs ? timeoutMs + 10_000 : undefined;
-        return makeApiCall("message", args, requestTimeout);
+        const requestTimeout = timeoutMs + 10_000;
+        return makeApiCall("message", { ...args, timeout_ms: timeoutMs }, requestTimeout);
     }
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
@@ -295,6 +397,9 @@ try {
                 case "update_space":
                     result = await handleUpdateSpace(args);
                     break;
+                case "update_folders":
+                    result = await handleUpdateFolders(args);
+                    break;
                 case "message":
                     result = await handleMessage(args);
                     break;

package/dist/tool-definitions.js

@@ -1,9 +1,9 @@
 // Tools definition - matches the stdio server
-export const TOOLS = [
+const TOOL_DEFINITIONS = [
     {
         name: "search",
         title: "Search Space",
-        description: "Search for context, tasks, skills, and projects within a space. System automatically extracts quantity from natural language ('show 3 tasks' → 3 results, 'the last one' → 1 result) and intelligently formats results (1-3 items → summaries, 4+ items → IDs only). Use fetch tool to get full content for specific IDs when needed.",
+        description: "Search for context, tasks, skills, and projects within a space. System automatically extracts quantity from natural language ('show 3 tasks' → 3 results, 'the last one' → 1 result) and intelligently formats results (1-3 items → summaries, 4+ items → IDs only). Default to one search per question, then use fetch_items for full details instead of repeating paraphrased searches.",
         inputSchema: {
             type: "object",
             properties: {
@@ -90,7 +90,7 @@ export const TOOLS = [
     {
         name: "start",
         title: "Start Space Session",
-        description: "Begin working in a space. Returns a dynamic briefing including: recent developments, current priorities, active tasks, user preferences for this space, and learned insights about how the user/org works. Use this context to personalize your assistance and anticipate needs.",
+        description: "Load a space fast for a new external caller. Returns assistant-curated current items, useful insights, skills, recent conversations, and assistant preferences so the caller can get oriented quickly and fetch deeper details only when needed.",
         inputSchema: {
             type: "object",
             properties: {
@@ -157,7 +157,7 @@ export const TOOLS = [
     {
         name: "update_memory",
         title: "Update Memory",
-        description: "Add, update, or delete items in a space. Supports any combination of operations in a single call.\n\nTIPS FOR RICH MEMORY: The more context you provide, the smarter the system becomes:\n- Include WHY something matters, not just WHAT it is\n- Note user preferences, patterns, and approaches you observe\n- Describe repeatable workflows as skills (step-by-step procedures)\n- Link related items using parent_id or linkedItemIds\n- Use descriptive titles that capture the essence\n- Add context about decisions, reasoning, and outcomes\n\nThe system learns from patterns - sharing how the user works helps it anticipate their needs.",
+        description: "Add, update, or delete items in a space. Supports any combination of operations in a single call.\n\nIMPORTANT: Include at least one operation: add, update, or delete.\n\nTIPS FOR RICH MEMORY: The more context you provide, the smarter the system becomes:\n- Include WHY something matters, not just WHAT it is\n- Note user preferences, patterns, and approaches you observe\n- Describe repeatable workflows as skills (step-by-step procedures)\n- Link related items using parent_id or linkedItemIds\n- Use descriptive titles that capture the essence\n- Add context about decisions, reasoning, and outcomes\n\nThe system learns from patterns - sharing how the user works helps it anticipate their needs.",
         inputSchema: {
             type: "object",
             properties: {
@@ -185,8 +185,8 @@ export const TOOLS = [
                                     },
                                     type: {
                                         type: "string",
-                                        enum: ["task", "context", "skill", "document"],
-                                        description: "REQUIRED: Item type. 'task' for actionable items, 'context' for knowledge/facts, 'skill' for workflows, 'document' for long-form reference material. Omitting this triggers expensive auto-classification."
+                                        enum: ["task", "context", "skill", "document", "insight"],
+                                        description: "REQUIRED: Item type. 'task' for actionable items, 'context' for knowledge/facts, 'skill' for workflows, 'document' for long-form reference material, 'insight' for durable patterns/principles. Omitting this triggers expensive auto-classification."
                                     },
                                     subtasks: {
                                         type: "array",
@@ -306,13 +306,117 @@ export const TOOLS = [
                     }
                 }
             },
-            required: ["space_id"]
+            required: ["space_id"],
+            anyOf: [{ required: ["add"] }, { required: ["update"] }, { required: ["delete"] }]
+        }
+    },
+    {
+        name: "update_folders",
+        title: "Update Folders",
+        description: "Unified folder management. Supports list, create, rename, move_items, and delete operations in one call so external MCP callers can organize memory the same way as the in-app assistant.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                space_id: {
+                    type: "string",
+                    description: "REQUIRED: Space to operate in (use view_spaces to see available options)."
+                },
+                list: {
+                    type: "object",
+                    description: "Optional list operation. Use this first to discover existing folders and IDs.",
+                    properties: {
+                        section_type: {
+                            type: "string",
+                            enum: [
+                                "projects",
+                                "insights",
+                                "insights_space",
+                                "insights_user",
+                                "agents",
+                                "skills",
+                                "conversations",
+                                "dashboard"
+                            ],
+                            description: "Optional: filter folders by sidebar section."
+                        }
+                    }
+                },
+                create: {
+                    type: "array",
+                    description: "Optional create operations.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string", description: "Folder name." },
+                            section_type: {
+                                type: "string",
+                                enum: [
+                                    "projects",
+                                    "insights",
+                                    "insights_space",
+                                    "insights_user",
+                                    "agents",
+                                    "skills",
+                                    "conversations",
+                                    "dashboard"
+                                ],
+                                description: "Sidebar section this folder belongs to."
+                            },
+                            parent_id: {
+                                type: "string",
+                                description: "Optional parent folder ID for nesting."
+                            }
+                        },
+                        required: ["name", "section_type"]
+                    }
+                },
+                rename: {
+                    type: "array",
+                    description: "Optional rename operations.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            folder_id: { type: "string", description: "Folder ID to rename." },
+                            new_name: { type: "string", description: "New folder name." }
+                        },
+                        required: ["folder_id", "new_name"]
+                    }
+                },
+                move_items: {
+                    type: "array",
+                    description: "Optional item move operations. Set folder_id to null to move an item back to root.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            item_id: { type: "string", description: "Item ID to move." },
+                            folder_id: {
+                                type: ["string", "null"],
+                                description: "Target folder ID, or null to remove from folder."
+                            }
+                        },
+                        required: ["item_id", "folder_id"]
+                    }
+                },
+                delete: {
+                    type: "array",
+                    description: "Optional delete operations (folder IDs).",
+                    items: { type: "string" }
+                }
+            },
+            required: ["space_id"],
+            anyOf: [
+                { required: ["list"] },
+                { required: ["create"] },
+                { required: ["rename"] },
+                { required: ["move_items"] },
+                { required: ["delete"] }
+            ]
         }
     },
     {
         name: "message",
         title: "Message Assistant",
-        description: "Send a user message to the Intangle assistant and wait for one assistant turn to complete. Returns assistant text, stop reason, session_id, and conversation_id for continuity.",
+        description: "Primary orchestration tool. Send a request to the Intangle assistant and wait for one assistant turn to complete. Returns assistant text plus continuity IDs (`session_id`, `conversation_id`) so callers can continue the same thread reliably across turns.",
         inputSchema: {
             type: "object",
             properties: {
@@ -330,11 +434,11 @@ export const TOOLS = [
                 },
                 conversation_id: {
                     type: "string",
-                    description: "Optional existing conversation/chat summary ID to resume continuity."
+                    description: "Optional existing conversation/chat summary ID to resume a specific conversation. If omitted, Intangle uses/creates the active conversation for this space."
                 },
                 session_id: {
                     type: "string",
-                    description: "Optional runtime session ID to reuse across multiple message calls."
+                    description: "Optional runtime session ID to reuse across calls. Reuse the returned session_id for best continuity and lower warm-up overhead."
                 },
                 project_id: {
                     type: "string",
@@ -355,9 +459,9 @@ export const TOOLS = [
             },
             required: ["space_id", "content"]
         }
-    },
+    }
     // DISABLED: memory_action tool is broken and causing errors.
-    // Pending OHM protocol fix. Use update_space, search, or fetch_items instead.
+    // Pending OHM protocol fix. Use update_memory, search, or fetch_items instead.
     // {
     //   name: "memory_action",
     //   title: "Memory Action (OHM Protocol)",
@@ -380,3 +484,31 @@ export const TOOLS = [
     //   }
     // }
 ];
+const READ_ONLY_TOOLS = new Set([
+    "search",
+    "fetch_items",
+    "start",
+    "view_spaces",
+    "view_space"
+]);
+const DESTRUCTIVE_TOOLS = new Set([
+    "create_space",
+    "update_memory",
+    "update_folders"
+]);
+const IDEMPOTENT_TOOLS = new Set([
+    "search",
+    "fetch_items",
+    "start",
+    "view_spaces",
+    "view_space"
+]);
+export const TOOLS = TOOL_DEFINITIONS.map((tool) => ({
+    ...tool,
+    annotations: {
+        ...(READ_ONLY_TOOLS.has(tool.name) ? { readOnlyHint: true } : {}),
+        ...(DESTRUCTIVE_TOOLS.has(tool.name) ? { destructiveHint: true } : {}),
+        ...(IDEMPOTENT_TOOLS.has(tool.name) ? { idempotentHint: true } : {}),
+        openWorldHint: true
+    }
+}));

package/index.ts

@@ -12,8 +12,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import {
   CallToolRequestSchema,
   ErrorCode,
+  ListResourceTemplatesRequestSchema,
+  ListResourcesRequestSchema,
   ListToolsRequestSchema,
   McpError,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js"
 import { config } from "dotenv"
 import fetch from "node-fetch"
@@ -134,6 +137,16 @@ try {
     return url.toString()
   }
 
+  function buildRemoteApiUrl() {
+    const url = new URL("/api/mcp-remote", API_BASE_URL)
+
+    if (VERCEL_BYPASS_TOKEN) {
+      url.searchParams.set("x-vercel-protection-bypass", VERCEL_BYPASS_TOKEN)
+    }
+
+    return url.toString()
+  }
+
   async function makeApiCall(endpoint: string, data: any, timeoutMs?: number) {
     // Ensure we have client info before making requests
     ensureClientInfo()
@@ -187,7 +200,9 @@ try {
           )
         }
 
-        throw new Error(`API call failed: ${response.status} ${response.statusText}`)
+        throw new Error(
+          `API call failed: ${response.status} ${response.statusText}`
+        )
       }
 
       if (responseBody.trim() === "") {
@@ -207,6 +222,70 @@ try {
     }
   }
 
+  async function makeRemoteRpcCall(
+    method: string,
+    params: Record<string, unknown>
+  ) {
+    ensureClientInfo()
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${MCP_API_KEY}`,
+      "User-Agent": mcpClientName
+        ? `${mcpClientName}/${mcpClientVersion || "unknown"} (mcp-stdio)`
+        : "MCP-Client-Stdio/1.1.2 (mcp)",
+    }
+
+    if (mcpClientName) {
+      headers["X-MCP-Client-Name"] = mcpClientName
+    }
+    if (mcpClientVersion) {
+      headers["X-MCP-Client-Version"] = mcpClientVersion
+    }
+    if (VERCEL_BYPASS_TOKEN) {
+      headers["x-vercel-protection-bypass"] = VERCEL_BYPASS_TOKEN
+    }
+
+    const requestId = Date.now()
+    const rpcBody = {
+      jsonrpc: "2.0",
+      id: requestId,
+      method,
+      params,
+    }
+
+    const response = await fetch(buildRemoteApiUrl(), {
+      method: "POST",
+      headers,
+      body: JSON.stringify(rpcBody),
+    })
+
+    const responseText = await response.text()
+    let responseJson: any = {}
+
+    try {
+      responseJson = responseText ? JSON.parse(responseText) : {}
+    } catch {
+      throw new Error(`Failed to parse MCP remote ${method} response`)
+    }
+
+    if (!response.ok) {
+      const message =
+        responseJson?.error?.message ||
+        responseJson?.message ||
+        `${response.status} ${response.statusText}`
+      throw new Error(`MCP remote ${method} failed: ${message}`)
+    }
+
+    if (responseJson?.error) {
+      const code = responseJson.error.code
+      const message = responseJson.error.message || "Unknown MCP remote error"
+      throw new Error(`MCP remote ${method} error (${code}): ${message}`)
+    }
+
+    return responseJson?.result ?? {}
+  }
+
   const server = new Server(
     {
       name: "intangle-context",
@@ -220,6 +299,7 @@ try {
     },
     {
       capabilities: {
+        resources: {},
         tools: {},
       },
     }
@@ -229,6 +309,34 @@ try {
     tools: TOOLS,
   }))
 
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const result = await makeRemoteRpcCall("resources/list", {})
+    return {
+      resources: Array.isArray(result?.resources) ? result.resources : [],
+      nextCursor:
+        typeof result?.nextCursor === "string" ? result.nextCursor : undefined,
+    }
+  })
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request: any) => {
+    const uri = request?.params?.uri
+    if (!uri || typeof uri !== "string") {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        "uri is required for resources/read"
+      )
+    }
+
+    const result = await makeRemoteRpcCall("resources/read", { uri })
+    return {
+      contents: Array.isArray(result?.contents) ? result.contents : [],
+    }
+  })
+
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates: [],
+  }))
+
   async function handleSearchContext(args: any) {
     const { space_id, query, topics } = args as {
       space_id: string
@@ -278,11 +386,15 @@ try {
     }
 
     if (!project_id && !slug) {
-      throw new Error("Either project_id or slug (with space_id) is required. Use view_projects to get valid IDs.")
+      throw new Error(
+        "Either project_id or slug (with space_id) is required. Use view_projects to get valid IDs."
+      )
     }
 
     if (slug && !space_id) {
-      throw new Error("space_id is required when using slug. Use view_spaces to see available options.")
+      throw new Error(
+        "space_id is required when using slug. Use view_spaces to see available options."
+      )
     }
 
     return makeApiCall("view-project", { project_id, space_id, slug })
@@ -310,9 +422,7 @@ try {
     }
 
     if (!args.add && !args.update && !args.delete) {
-      throw new Error(
-        "At least one operation must be provided"
-      )
+      throw new Error("At least one operation must be provided")
     }
 
     // Ensure all add items have a type field to prevent classification timeout
@@ -320,7 +430,9 @@ try {
     if (add?.items && Array.isArray(add.items)) {
       for (const item of add.items) {
         if (!item.type) {
-          log(`WARNING: Item "${item.title}" missing type field, defaulting to "context" to prevent classification timeout`)
+          log(
+            `WARNING: Item "${item.title}" missing type field, defaulting to "context" to prevent classification timeout`
+          )
           item.type = "context"
         }
       }
@@ -336,20 +448,56 @@ try {
     })
   }
 
+  async function handleUpdateFolders(args: any) {
+    if (!args.space_id) {
+      throw new Error(
+        "space_id is required. Use view_spaces to see available options."
+      )
+    }
+
+    const hasOperation =
+      !!args.list ||
+      (Array.isArray(args.create) && args.create.length > 0) ||
+      (Array.isArray(args.rename) && args.rename.length > 0) ||
+      (Array.isArray(args.move_items) && args.move_items.length > 0) ||
+      (Array.isArray(args.delete) && args.delete.length > 0)
+
+    if (!hasOperation) {
+      throw new Error(
+        "At least one operation is required: list, create, rename, move_items, or delete."
+      )
+    }
+
+    return makeApiCall("update-folders", {
+      space_id: args.space_id,
+      list: args.list,
+      create: args.create,
+      rename: args.rename,
+      move_items: args.move_items,
+      delete: args.delete,
+    })
+  }
+
   async function handleMessage(args: any) {
     if (!args.space_id || !args.content) {
       throw new Error("space_id and content are required")
     }
 
+    // Keep one-turn MCP calls safely under common external tool-call deadlines
+    // while still allowing caller override for longer jobs.
     const timeoutMs =
       typeof args.timeout_ms === "number" && Number.isFinite(args.timeout_ms)
         ? Math.max(10_000, Math.min(300_000, Math.trunc(args.timeout_ms)))
-        : undefined
+        : 100_000
 
     // Give backend a little extra headroom beyond requested assistant timeout.
-    const requestTimeout = timeoutMs ? timeoutMs + 10_000 : undefined
+    const requestTimeout = timeoutMs + 10_000
 
-    return makeApiCall("message", args, requestTimeout)
+    return makeApiCall(
+      "message",
+      { ...args, timeout_ms: timeoutMs },
+      requestTimeout
+    )
   }
 
   server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
@@ -388,6 +536,9 @@ try {
         case "update_space":
           result = await handleUpdateSpace(args)
           break
+        case "update_folders":
+          result = await handleUpdateFolders(args)
+          break
         case "message":
           result = await handleMessage(args)
           break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intangle/mcp-server",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "description": "Model Context Protocol server for Intangle - AI context that persists across conversations",
   "main": "dist/index.js",
   "type": "module",

package/tool-definitions.ts

@@ -1,10 +1,10 @@
 // Tools definition - matches the stdio server
-export const TOOLS = [
+const TOOL_DEFINITIONS = [
   {
     name: "search",
     title: "Search Space",
     description:
-      "Search for context, tasks, skills, and projects within a space. System automatically extracts quantity from natural language ('show 3 tasks' → 3 results, 'the last one' → 1 result) and intelligently formats results (1-3 items → summaries, 4+ items → IDs only). Use fetch tool to get full content for specific IDs when needed.",
+      "Search for context, tasks, skills, and projects within a space. System automatically extracts quantity from natural language ('show 3 tasks' → 3 results, 'the last one' → 1 result) and intelligently formats results (1-3 items → summaries, 4+ items → IDs only). Default to one search per question, then use fetch_items for full details instead of repeating paraphrased searches.",
     inputSchema: {
       type: "object",
       properties: {
@@ -97,7 +97,7 @@ export const TOOLS = [
     name: "start",
     title: "Start Space Session",
     description:
-      "Begin working in a space. Returns a dynamic briefing including: recent developments, current priorities, active tasks, user preferences for this space, and learned insights about how the user/org works. Use this context to personalize your assistance and anticipate needs.",
+      "Load a space fast for a new external caller. Returns assistant-curated current items, useful insights, skills, recent conversations, and assistant preferences so the caller can get oriented quickly and fetch deeper details only when needed.",
     inputSchema: {
       type: "object",
       properties: {
@@ -171,7 +171,7 @@ export const TOOLS = [
     name: "update_memory",
     title: "Update Memory",
     description:
-      "Add, update, or delete items in a space. Supports any combination of operations in a single call.\n\nTIPS FOR RICH MEMORY: The more context you provide, the smarter the system becomes:\n- Include WHY something matters, not just WHAT it is\n- Note user preferences, patterns, and approaches you observe\n- Describe repeatable workflows as skills (step-by-step procedures)\n- Link related items using parent_id or linkedItemIds\n- Use descriptive titles that capture the essence\n- Add context about decisions, reasoning, and outcomes\n\nThe system learns from patterns - sharing how the user works helps it anticipate their needs.",
+      "Add, update, or delete items in a space. Supports any combination of operations in a single call.\n\nIMPORTANT: Include at least one operation: add, update, or delete.\n\nTIPS FOR RICH MEMORY: The more context you provide, the smarter the system becomes:\n- Include WHY something matters, not just WHAT it is\n- Note user preferences, patterns, and approaches you observe\n- Describe repeatable workflows as skills (step-by-step procedures)\n- Link related items using parent_id or linkedItemIds\n- Use descriptive titles that capture the essence\n- Add context about decisions, reasoning, and outcomes\n\nThe system learns from patterns - sharing how the user works helps it anticipate their needs.",
     inputSchema: {
       type: "object",
       properties: {
@@ -203,9 +203,9 @@ export const TOOLS = [
                   },
                   type: {
                     type: "string",
-                    enum: ["task", "context", "skill", "document"],
+                    enum: ["task", "context", "skill", "document", "insight"],
                     description:
-                      "REQUIRED: Item type. 'task' for actionable items, 'context' for knowledge/facts, 'skill' for workflows, 'document' for long-form reference material. Omitting this triggers expensive auto-classification."
+                      "REQUIRED: Item type. 'task' for actionable items, 'context' for knowledge/facts, 'skill' for workflows, 'document' for long-form reference material, 'insight' for durable patterns/principles. Omitting this triggers expensive auto-classification."
                   },
                   subtasks: {
                     type: "array",
@@ -339,14 +339,122 @@ export const TOOLS = [
           }
         }
       },
-      required: ["space_id"]
+      required: ["space_id"],
+      anyOf: [{ required: ["add"] }, { required: ["update"] }, { required: ["delete"] }]
+    }
+  },
+  {
+    name: "update_folders",
+    title: "Update Folders",
+    description:
+      "Unified folder management. Supports list, create, rename, move_items, and delete operations in one call so external MCP callers can organize memory the same way as the in-app assistant.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        space_id: {
+          type: "string",
+          description:
+            "REQUIRED: Space to operate in (use view_spaces to see available options)."
+        },
+        list: {
+          type: "object",
+          description:
+            "Optional list operation. Use this first to discover existing folders and IDs.",
+          properties: {
+            section_type: {
+              type: "string",
+              enum: [
+                "projects",
+                "insights",
+                "insights_space",
+                "insights_user",
+                "agents",
+                "skills",
+                "conversations",
+                "dashboard"
+              ],
+              description: "Optional: filter folders by sidebar section."
+            }
+          }
+        },
+        create: {
+          type: "array",
+          description: "Optional create operations.",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string", description: "Folder name." },
+              section_type: {
+                type: "string",
+                enum: [
+                  "projects",
+                  "insights",
+                  "insights_space",
+                  "insights_user",
+                  "agents",
+                  "skills",
+                  "conversations",
+                  "dashboard"
+                ],
+                description: "Sidebar section this folder belongs to."
+              },
+              parent_id: {
+                type: "string",
+                description: "Optional parent folder ID for nesting."
+              }
+            },
+            required: ["name", "section_type"]
+          }
+        },
+        rename: {
+          type: "array",
+          description: "Optional rename operations.",
+          items: {
+            type: "object",
+            properties: {
+              folder_id: { type: "string", description: "Folder ID to rename." },
+              new_name: { type: "string", description: "New folder name." }
+            },
+            required: ["folder_id", "new_name"]
+          }
+        },
+        move_items: {
+          type: "array",
+          description:
+            "Optional item move operations. Set folder_id to null to move an item back to root.",
+          items: {
+            type: "object",
+            properties: {
+              item_id: { type: "string", description: "Item ID to move." },
+              folder_id: {
+                type: ["string", "null"],
+                description: "Target folder ID, or null to remove from folder."
+              }
+            },
+            required: ["item_id", "folder_id"]
+          }
+        },
+        delete: {
+          type: "array",
+          description: "Optional delete operations (folder IDs).",
+          items: { type: "string" }
+        }
+      },
+      required: ["space_id"],
+      anyOf: [
+        { required: ["list"] },
+        { required: ["create"] },
+        { required: ["rename"] },
+        { required: ["move_items"] },
+        { required: ["delete"] }
+      ]
     }
   },
   {
     name: "message",
     title: "Message Assistant",
     description:
-      "Send a user message to the Intangle assistant and wait for one assistant turn to complete. Returns assistant text, stop reason, session_id, and conversation_id for continuity.",
+      "Primary orchestration tool. Send a request to the Intangle assistant and wait for one assistant turn to complete. Returns assistant text plus continuity IDs (`session_id`, `conversation_id`) so callers can continue the same thread reliably across turns.",
     inputSchema: {
       type: "object",
       properties: {
@@ -366,12 +474,12 @@ export const TOOLS = [
         conversation_id: {
           type: "string",
           description:
-            "Optional existing conversation/chat summary ID to resume continuity."
+            "Optional existing conversation/chat summary ID to resume a specific conversation. If omitted, Intangle uses/creates the active conversation for this space."
         },
         session_id: {
           type: "string",
           description:
-            "Optional runtime session ID to reuse across multiple message calls."
+            "Optional runtime session ID to reuse across calls. Reuse the returned session_id for best continuity and lower warm-up overhead."
         },
         project_id: {
           type: "string",
@@ -394,9 +502,9 @@ export const TOOLS = [
       },
       required: ["space_id", "content"]
     }
-  },
+  }
   // DISABLED: memory_action tool is broken and causing errors.
-  // Pending OHM protocol fix. Use update_space, search, or fetch_items instead.
+  // Pending OHM protocol fix. Use update_memory, search, or fetch_items instead.
   // {
   //   name: "memory_action",
   //   title: "Memory Action (OHM Protocol)",
@@ -419,3 +527,35 @@ export const TOOLS = [
   //   }
   // }
 ]
+
+const READ_ONLY_TOOLS = new Set([
+  "search",
+  "fetch_items",
+  "start",
+  "view_spaces",
+  "view_space"
+])
+
+const DESTRUCTIVE_TOOLS = new Set([
+  "create_space",
+  "update_memory",
+  "update_folders"
+])
+
+const IDEMPOTENT_TOOLS = new Set([
+  "search",
+  "fetch_items",
+  "start",
+  "view_spaces",
+  "view_space"
+])
+
+export const TOOLS = TOOL_DEFINITIONS.map((tool) => ({
+  ...tool,
+  annotations: {
+    ...(READ_ONLY_TOOLS.has(tool.name) ? { readOnlyHint: true } : {}),
+    ...(DESTRUCTIVE_TOOLS.has(tool.name) ? { destructiveHint: true } : {}),
+    ...(IDEMPOTENT_TOOLS.has(tool.name) ? { idempotentHint: true } : {}),
+    openWorldHint: true
+  }
+}))