@hailer/mcp 1.2.1 → 1.3.9

package/dist/mcp/tools/activity.js

@@ -10,6 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.activityTools = exports.updateActivityTool = exports.createActivityTool = exports.showActivityByIdTool = exports.listActivitiesTool = void 0;
+exports.mergeBulkPage = mergeBulkPage;
 const zod_1 = require("zod");
 const tool_registry_1 = require("../tool-registry");
 const index_1 = require("../utils/index");
@@ -32,7 +33,7 @@ function validateAndGetWorkflow(workflowId, init) {
  */
 async function resolvePhaseForListing(workflow, args, _init) {
     if (!args.phaseId) {
-        throw new Error(`Phase ID is required. Use the list_workflow_phases tool to get available phase IDs for workflow "${workflow.name}".`);
+        throw new Error(`Phase ID is required. Use describe_workflows with include: ['phases'] to get available phase IDs for workflow "${workflow.name}".`);
     }
     return args.phaseId;
 }
@@ -98,7 +99,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
     let malformatFilterErrorMessage = undefined;
     for (const [fieldId, filterConfig] of Object.entries(mcpToolActivityListFilters)) {
         switch (filterConfig.operator) {
-            case "text_search":
+            case 'text_search':
                 if (filterConfig.value !== undefined) {
                     apiActivityFilters.and.push({ [fieldId]: { textSearch: filterConfig.value } });
                 }
@@ -106,7 +107,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'text_search filter requires a value';
                 }
                 break;
-            case "equals":
+            case 'equals':
                 if (filterConfig.value !== undefined) {
                     apiActivityFilters.and.push({ [fieldId]: { equalTo: filterConfig.value } });
                 }
@@ -114,7 +115,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'equals filter requires a value';
                 }
                 break;
-            case "not_equals":
+            case 'not_equals':
                 if (filterConfig.value !== undefined) {
                     apiActivityFilters.and.push({ [fieldId]: { notEqualTo: filterConfig.value } });
                 }
@@ -122,7 +123,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'not_equals filter requires a value';
                 }
                 break;
-            case "contains":
+            case 'contains':
                 if (filterConfig.value !== undefined) {
                     apiActivityFilters.and.push({ [fieldId]: { contains: filterConfig.value } });
                 }
@@ -130,7 +131,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'contains filter requires a value';
                 }
                 break;
-            case "greater_than":
+            case 'greater_than':
                 if (filterConfig.value !== undefined && typeof filterConfig.value === 'number') {
                     apiActivityFilters.and.push({ [fieldId]: { greaterThan: filterConfig.value } });
                 }
@@ -138,7 +139,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'greater_than filter requires a numeric value';
                 }
                 break;
-            case "greater_than_or_equal":
+            case 'greater_than_or_equal':
                 if (filterConfig.value !== undefined && typeof filterConfig.value === 'number') {
                     apiActivityFilters.and.push({ [fieldId]: { greaterThanOrEqual: filterConfig.value } });
                 }
@@ -146,7 +147,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'greater_than_or_equal filter requires a numeric value';
                 }
                 break;
-            case "less_than":
+            case 'less_than':
                 if (filterConfig.value !== undefined && typeof filterConfig.value === 'number') {
                     apiActivityFilters.and.push({ [fieldId]: { lessThan: filterConfig.value } });
                 }
@@ -154,7 +155,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'less_than filter requires a numeric value';
                 }
                 break;
-            case "less_than_or_equal":
+            case 'less_than_or_equal':
                 if (filterConfig.value !== undefined && typeof filterConfig.value === 'number') {
                     apiActivityFilters.and.push({ [fieldId]: { lessThanOrEqual: filterConfig.value } });
                 }
@@ -162,7 +163,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'less_than_or_equal filter requires a numeric value';
                 }
                 break;
-            case "range":
+            case 'range':
                 if (!filterConfig.start || !filterConfig.end) {
                     malformatFilterErrorMessage = 'Incorrect filter format, either start or end not provided for range';
                     break;
@@ -181,19 +182,27 @@ function convertActivityFilters(mcpToolActivityListFilters) {
  */
 function formatActivityListResponseWithPagination(activityData, workflow, init, phaseName, args) {
     const activities = Array.isArray(activityData) ? activityData : (activityData.activities || activityData || []);
+    const metadata = (!Array.isArray(activityData) && activityData.metadata) || {};
     const cleanedActivities = (0, index_1.transformActivities)(activities, workflow, init.users);
     const filteredActivities = args?.fields
         ? filterFieldsAndValues(cleanedActivities, args.fields, workflow.fields)
         : cleanedActivities;
     const currentPage = args?.page || 0;
     const limit = args?.limit || 50;
-    const hasMorePages = activities.length === limit;
+    // The server always returns metadata.totalCount — use it for exact page math
+    // instead of the old length === limit guess (0 means the count query failed).
+    const reportedTotal = typeof metadata.totalCount === 'number' && metadata.totalCount > 0 ? metadata.totalCount : 0;
+    const totalPages = reportedTotal > 0 ? Math.ceil(reportedTotal / limit) : undefined;
+    const hasMorePages = reportedTotal > 0 ? (currentPage + 1) * limit < reportedTotal : activities.length === limit;
     let responseText = `📊 **PAGINATION INFO:**\n`;
-    responseText += `- Current page: ${currentPage + 1}\n`;
+    responseText += `- Current page: ${currentPage + 1}${totalPages ? ` of ${totalPages}` : ''}\n`;
+    if (reportedTotal > 0) {
+        responseText += `- Total matching activities: ${reportedTotal}\n`;
+    }
     responseText += `- Activities on this page: ${activities.length}\n`;
     responseText += `- Limit per page: ${limit}\n`;
     if (hasMorePages) {
-        responseText += `- ⚠️  **MORE DATA AVAILABLE**: Use page=${currentPage + 1} to get next ${limit} activities\n`;
+        responseText += `- ⚠️  **MORE DATA AVAILABLE**: Use page=${currentPage + 1} to get the next ${limit} activities\n`;
     }
     if (activities.length === limit && currentPage === 0) {
         responseText += `\n💡 **TIP**: This shows the first ${limit} activities.\n`;
@@ -205,7 +214,7 @@ function formatActivityListResponseWithPagination(activityData, workflow, init,
     return {
         content: [
             {
-                type: "text",
+                type: 'text',
                 text: responseText,
             },
         ],
@@ -221,22 +230,27 @@ function formatFilteredActivityListResponse(activityData, workflow, init, args)
     const filteredActivities = args.fields
         ? filterFieldsAndValues(cleanedActivities, args.fields, workflow.fields)
         : cleanedActivities;
-    const totalCount = metadata.totalCount || activities.length;
     const currentPage = args?.page || 0;
     const limit = args?.limit || 50;
-    const hasMorePages = activities.length === limit;
-    const totalPages = Math.ceil(totalCount / limit);
+    // 0 means the count query failed — fall back to the full-page heuristic
+    // instead of declaring a full page complete.
+    const reportedTotal = typeof metadata.totalCount === 'number' && metadata.totalCount > 0 ? metadata.totalCount : 0;
+    const totalCount = reportedTotal || activities.length;
+    const hasMorePages = reportedTotal > 0 ? (currentPage + 1) * limit < reportedTotal : activities.length === limit;
+    const totalPages = Math.max(1, Math.ceil(totalCount / limit));
     let responseText = `🎯 **FILTERED ACTIVITIES** in "${workflow.name}":\n\n`;
     const filterCount = Object.keys(args.filters || {}).length;
     responseText += `**Applied Filters:** ${filterCount} field filter(s)\n`;
     for (const [fieldId, filter] of Object.entries(args.filters || {})) {
         const filterConfig = filter;
         responseText += `- Field \`${fieldId}\`: ${filterConfig.operator}`;
-        if (filterConfig.value !== undefined)
+        if (filterConfig.value !== undefined) {
             responseText += ` = "${filterConfig.value}"`;
-        if (filterConfig.start !== undefined)
+        }
+        if (filterConfig.start !== undefined) {
             responseText += ` from ${filterConfig.start} to ${filterConfig.end}`;
-        responseText += "\n";
+        }
+        responseText += '\n';
     }
     if (args.search) {
         responseText += `- Text search: "${args.search}"\n`;
@@ -254,10 +268,10 @@ function formatFilteredActivityListResponse(activityData, workflow, init, args)
         responseText += `💡 **TROUBLESHOOTING:**\n`;
         responseText += `- Try broader filter criteria\n`;
         responseText += `- Remove some filters to see if data exists\n`;
-        responseText += `- Call get_workflow_schema to verify field IDs are correct\n`;
+        responseText += `- Call describe_workflows with include: ['schema'] to verify field IDs are correct\n`;
         responseText += `- Use list_activities without filters to see all activities`;
         return {
-            content: [{ type: "text", text: responseText }],
+            content: [{ type: 'text', text: responseText }],
         };
     }
     responseText += `\n` + (0, index_1.formatActivityListResponse)(filteredActivities, workflow, undefined);
@@ -266,23 +280,273 @@ function formatFilteredActivityListResponse(activityData, workflow, init, args)
     responseText += `- Use 'range' operator for date/number ranges (created/updated timestamps)\n`;
     responseText += `- Use 'contains' or 'text_search' for partial text matching\n`;
     responseText += `- Combine multiple filters for precise results\n`;
-    responseText += `- Call get_workflow_schema to discover available fields and their types`;
+    responseText += `- Call describe_workflows with include: ['schema'] to discover available fields and their types`;
     return {
         content: [
             {
-                type: "text",
+                type: 'text',
                 text: responseText,
             },
         ],
     };
 }
+// Bulk reads: the backend reliably serves at most ~200 activities per call
+// (larger limits fail silently as []), so "a lot of data at once" means many
+// skip-pages — fetched in parallel inside ONE tool call instead of one model
+// turn per page.
+const BULK_PAGE_SIZE = 200;
+const BULK_CONCURRENCY = 5;
+const BULK_MAX_RECORDS = 5000;
+/** Merges one page response into the accumulator; returns the page's row count. */
+function mergeBulkPage(pageResult, byId) {
+    const activities = Array.isArray(pageResult) ? pageResult : (pageResult?.activities || []);
+    for (const activity of activities) {
+        byId.set(activity._id, activity);
+    }
+    return activities.length;
+}
+/**
+ * Bulk-read body of list_activities (maxRecords). Pages are fetched sorted
+ * created asc: skip pagination over the default updated-desc ordering shifts
+ * rows across page boundaries mid-fetch (duplicates/gaps); created order is
+ * append-only. Page one runs alone to learn totalCount, the rest run in
+ * parallel batches. An empty non-final page means the backend query failed
+ * (it reports errors as empty results) — surfaced loudly, never as "no data".
+ */
+async function executeBulkRead(args, workflow, phaseId, apiFilters, context) {
+    const fetchPage = (pageIndex) => context.hailer.fetchActivityList(args.workflowId, phaseId, BULK_PAGE_SIZE, {
+        page: pageIndex,
+        search: args.search,
+        sortBy: 'created',
+        sortOrder: 'asc',
+        filters: apiFilters,
+        returnFlat: true,
+    });
+    const firstPage = await fetchPage(0);
+    const byId = new Map();
+    const firstPageCount = mergeBulkPage(firstPage, byId);
+    const totalCount = typeof firstPage?.metadata?.totalCount === 'number' ? firstPage.metadata.totalCount : 0;
+    const requested = Math.min(args.maxRecords || BULK_PAGE_SIZE, BULK_MAX_RECORDS);
+    let failedPages = 0;
+    let maybeMore = false;
+    if (totalCount === 0 && firstPageCount === BULK_PAGE_SIZE) {
+        // Count query failed (0) but the first page is full — the total is
+        // unknown. Walk pages sequentially until a short page so a 200-row cap
+        // is never silently presented as the complete dataset.
+        let pageIndex = 1;
+        let lastCount = firstPageCount;
+        while (lastCount === BULK_PAGE_SIZE && byId.size < requested) {
+            const result = await fetchPage(pageIndex).catch(() => null);
+            if (!result) {
+                failedPages += 1;
+                break;
+            }
+            lastCount = mergeBulkPage(result, byId);
+            pageIndex += 1;
+        }
+        maybeMore = lastCount === BULK_PAGE_SIZE && byId.size >= requested;
+    }
+    const target = Math.min(requested, Math.max(totalCount, byId.size));
+    const pageCount = Math.max(1, Math.ceil(target / BULK_PAGE_SIZE));
+    for (let start = 1; start < pageCount && totalCount > 0; start += BULK_CONCURRENCY) {
+        const end = Math.min(start + BULK_CONCURRENCY, pageCount);
+        const batch = [];
+        for (let pageIndex = start; pageIndex < end; pageIndex += 1) {
+            batch.push(fetchPage(pageIndex).catch(() => null));
+        }
+        const results = await Promise.all(batch);
+        for (const result of results) {
+            const merged = result ? mergeBulkPage(result, byId) : 0;
+            if (merged === 0) {
+                failedPages += 1;
+            }
+        }
+    }
+    const allActivities = Array.from(byId.values()).slice(0, target);
+    const displayTotal = Math.max(totalCount, allActivities.length);
+    const cleanedActivities = (0, index_1.transformActivities)(allActivities, workflow, context.init.users);
+    const projectedActivities = args.fields
+        ? filterFieldsAndValues(cleanedActivities, args.fields, workflow.fields)
+        : cleanedActivities;
+    let responseText = `📦 **BULK FETCH:**\n`;
+    responseText += `- Retrieved: ${allActivities.length} of ${displayTotal} matching activities (${pageCount} page(s) in parallel)\n`;
+    if (displayTotal > requested) {
+        responseText += `- ℹ️ Only the first ${requested} were fetched (maxRecords). ` +
+            `${displayTotal - requested} more match — raise maxRecords (max ${BULK_MAX_RECORDS}) or narrow with filters\n`;
+    }
+    if (allActivities.length < target || failedPages > 0) {
+        responseText += `- ⚠️ **INCOMPLETE**: expected ${target} but got ${allActivities.length}` +
+            `${failedPages ? ` (${failedPages} page(s) returned empty/failed)` : ''}. ` +
+            `Retry, or narrow with filters — do NOT treat this as the full dataset\n`;
+    }
+    if (maybeMore) {
+        responseText += `- ⚠️ The server's total count was unavailable and the last page was full — ` +
+            `more activities likely exist beyond maxRecords. Raise maxRecords or narrow with filters\n`;
+    }
+    responseText += `\n` + (0, index_1.formatActivityListResponse)(projectedActivities, workflow);
+    return {
+        content: [{ type: 'text', text: responseText }],
+    };
+}
+/**
+ * countOnly fast path for list_activities — preserved verbatim from the retired
+ * count_activities tool. O(1): calls v3.activity.count, never fetches activities.
+ */
+async function executeActivityCount(workflowId, context) {
+    logger.debug('Counting activities', {
+        workflowId,
+        apiKey: context.apiKey.substring(0, 8) + '...',
+    });
+    try {
+        // Get workflow name from cached data (matches by _id or key)
+        const workflow = (context.init.processes || []).find((proc) => proc._id === workflowId || proc.key === workflowId);
+        if (!workflow) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `❌ Workflow "${workflowId}" not found`,
+                    }],
+            };
+        }
+        logger.debug('Calling v3.activity.count', {
+            workflowId,
+            workflowName: workflow.name,
+        });
+        // Call v3.activity.count endpoint
+        // Returns object with phase IDs as keys and counts as values
+        const result = await context.hailer.request('v3.activity.count', [workflowId]);
+        logger.debug('Activity count retrieved', {
+            result: JSON.stringify(result),
+        });
+        // Sum all counts across phases
+        const count = Object.values(result).reduce((sum, phaseCount) => sum + phaseCount, 0);
+        let responseText = `🔢 **Activity Count for "${workflow.name}"**\n\n`;
+        responseText += `**Workflow ID:** \`${workflowId}\`\n`;
+        responseText += `**Total Activities:** ${count}\n\n`;
+        if (count === 0) {
+            responseText += `💡 This workflow has no activities yet. Use \`create_activity\` to add one.\n`;
+            return {
+                content: [{ type: 'text', text: responseText }],
+            };
+        }
+        responseText += `💡 **Next Steps:**\n`;
+        responseText += `- Use \`list_activities\` to see the activities\n`;
+        responseText += `- Use \`describe_workflows\` with include: ['schema'] to see workflow structure\n`;
+        return {
+            content: [{ type: 'text', text: responseText }],
+        };
+    }
+    catch (error) {
+        if (!request_logger_1.RequestLogger.getCurrent()) {
+            logger.error('Error counting activities', error);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ Error counting activities: ${error instanceof Error ? error.message : String(error)}\n\n**Tips:**\n` +
+                        '- Check that workflow ID is valid (24 characters)\n- Use `describe_workflows` to find workflow IDs',
+                }],
+        };
+    }
+}
+/**
+ * Validate the keys of a fields object against a workflow's field definitions.
+ * The server silently ignores unknown keys (e.g. field NAMES instead of IDs) and
+ * reports success — the #1 documented footgun — so we error out before the API call.
+ *
+ * ORDERING: in both create_activity and update_activity this runs AFTER the
+ * date/activitylink auto-fixups and immediately before the API call. The fixups
+ * rewrite values only, never keys, so the validated key set is identical either way.
+ *
+ * Accepts field IDs and field keys (the API resolves both).
+ * Returns error text for unknown keys, or undefined when all keys are known.
+ */
+function validateFieldKeys(fields, workflowFields) {
+    const knownKeys = new Set();
+    const labelToId = new Map();
+    for (const [fieldId, fieldDef] of Object.entries(workflowFields)) {
+        const def = fieldDef;
+        knownKeys.add(fieldId);
+        if (def.key) {
+            knownKeys.add(def.key);
+        }
+        if (def.label) {
+            labelToId.set(String(def.label).toLowerCase(), fieldId);
+        }
+    }
+    const unknownKeys = Object.keys(fields).filter((key) => !knownKeys.has(key));
+    if (unknownKeys.length === 0) {
+        return undefined;
+    }
+    const lines = [];
+    let needsFieldList = false;
+    for (const key of unknownKeys) {
+        const labelMatchId = labelToId.get(key.toLowerCase());
+        if (labelMatchId) {
+            const label = workflowFields[labelMatchId].label;
+            lines.push(`Field "${key}" must be referenced by ID: use "${labelMatchId}" (label: "${label}")`);
+            continue;
+        }
+        lines.push(`Unknown field key "${key}".`);
+        needsFieldList = true;
+    }
+    if (needsFieldList) {
+        const available = Object.entries(workflowFields)
+            .slice(0, 20)
+            .map(([fid, def]) => `- "${fid}" (label: "${def.label || def.key || fid}")`);
+        lines.push('', 'Available field IDs:', ...available);
+    }
+    return lines.join('\n');
+}
+/**
+ * update_activity field-key validation: resolves the activity's workflow (the
+ * workflowId is not a tool param) via fetchActivityById → activity.process, then
+ * validates the fields object's keys. Fail-open on resolution problems (broken
+ * function fields, deleted activity, workflow missing from init) — those must not
+ * block updates; unknown keys in a resolved workflow still hard-error.
+ * Returns formatted error text, or undefined when valid or unresolvable.
+ */
+async function validateUpdateFieldKeys(activityId, fields, context, knownWorkflowFields) {
+    if (Object.keys(fields).length === 0) {
+        return undefined;
+    }
+    let workflowFields = knownWorkflowFields;
+    if (!workflowFields) {
+        try {
+            const activity = await context.hailer.fetchActivityById(activityId);
+            const workflow = context.init.processes?.find((proc) => proc._id === activity?.process);
+            workflowFields = workflow?.fields;
+        }
+        catch (error) {
+            logger.warn('Skipping field-key validation - could not resolve workflow for activity', {
+                activityId,
+                error: (0, tool_helpers_1.extractErrorMessage)(error),
+            });
+            return undefined;
+        }
+    }
+    if (!workflowFields) {
+        return undefined;
+    }
+    const keyError = validateFieldKeys(fields, workflowFields);
+    if (!keyError) {
+        return undefined;
+    }
+    if (knownWorkflowFields) {
+        // The caller-supplied workflowId may simply be wrong for this activity —
+        // re-resolve the workflow from the activity itself before rejecting.
+        return validateUpdateFieldKeys(activityId, fields, context);
+    }
+    return `❌ Invalid field keys for activity ${activityId} — nothing was updated.\n\n${keyError}`;
+}
 /** Auto-fix date fields: convert ISO date strings to Unix timestamps (ms).
  *  If workspaceCache is available, only converts confirmed date/datetime/time fields.
  *  If not available, converts any value matching ISO date format (safe — non-date fields won't have date strings). */
 function autoFixDateFields(fields, context) {
     for (const [fieldId, fieldValue] of Object.entries(fields)) {
-        if (typeof fieldValue !== 'string' || !/^\d{4}-\d{2}-\d{2}/.test(fieldValue))
+        if (typeof fieldValue !== 'string' || !/^\d{4}-\d{2}-\d{2}/.test(fieldValue)) {
             continue;
+        }
         // Try to confirm field type from cache
         let fieldType;
         if (context.workspaceCache) {
@@ -297,15 +561,16 @@ function autoFixDateFields(fields, context) {
         // Convert if confirmed date type, OR if no cache (assume date — non-date fields won't have ISO date strings)
         if (!fieldType || fieldType === 'date' || fieldType === 'datetime' || fieldType === 'time') {
             const parsed = new Date(fieldValue.length === 10 ? fieldValue + 'T12:00:00' : fieldValue).getTime();
-            if (!isNaN(parsed))
+            if (!isNaN(parsed)) {
                 fields[fieldId] = parsed;
+            }
         }
     }
 }
 /** Build activity update object */
 function buildActivityUpdate(args, context) {
     let parsedFields = args.fields;
-    if (typeof args.fields === "string") {
+    if (typeof args.fields === 'string') {
         try {
             parsedFields = JSON.parse(args.fields);
         }
@@ -314,25 +579,25 @@ function buildActivityUpdate(args, context) {
         }
     }
     // Auto-fix activitylink fields: if LLM passes an object instead of just the ID string
-    if (parsedFields && typeof parsedFields === "object") {
+    if (parsedFields && typeof parsedFields === 'object') {
         for (const [fieldId, fieldValue] of Object.entries(parsedFields)) {
-            if (fieldValue && typeof fieldValue === "object" && !Array.isArray(fieldValue)) {
+            if (fieldValue && typeof fieldValue === 'object' && !Array.isArray(fieldValue)) {
                 const obj = fieldValue;
                 let extractedId = null;
                 // Case 1: {type: "activitylink", value: {_id: "...", name: "..."}}
-                if (obj.type && obj.value && typeof obj.value === "object" && obj.value._id) {
+                if (obj.type && obj.value && typeof obj.value === 'object' && obj.value._id) {
                     extractedId = obj.value._id;
                 }
                 // Case 2: {_id: "...", name: "..."}
-                else if (obj._id && typeof obj._id === "string") {
+                if (!extractedId && obj._id && typeof obj._id === 'string') {
                     extractedId = obj._id;
                 }
                 // Case 3: {value: "..."} where value is the ID string
-                else if (obj.value && typeof obj.value === "string" && /^[a-f0-9]{24}$/i.test(obj.value)) {
+                if (!extractedId && obj.value && typeof obj.value === 'string' && /^[a-f0-9]{24}$/i.test(obj.value)) {
                     extractedId = obj.value;
                 }
                 if (extractedId) {
-                    logger.warn("Auto-fixing activitylink field - extracting ID from object", {
+                    logger.warn('Auto-fixing activitylink field - extracting ID from object', {
                         fieldId,
                         original: JSON.stringify(fieldValue),
                         extracted: extractedId,
@@ -343,20 +608,21 @@ function buildActivityUpdate(args, context) {
         }
     }
     // Field-type aware validation and auto-fix
-    if (parsedFields && typeof parsedFields === "object" && context.workspaceCache) {
+    if (parsedFields && typeof parsedFields === 'object' && context.workspaceCache) {
         autoFixDateFields(parsedFields, context);
         const invalidUsers = [];
         for (const [fieldId, fieldValue] of Object.entries(parsedFields)) {
             // Only check string values that look like IDs
-            if (typeof fieldValue !== "string" || !/^[a-f0-9]{24}$/i.test(fieldValue)) {
+            if (typeof fieldValue !== 'string' || !/^[a-f0-9]{24}$/i.test(fieldValue)) {
                 continue;
             }
             // Find the field definition to check its type
             let fieldType;
             for (const workflow of context.workspaceCache.rawInit.processes) {
                 const workflowFields = workflow.fields;
-                if (!workflowFields)
+                if (!workflowFields) {
                     continue;
+                }
                 const field = workflowFields[fieldId];
                 if (field) {
                     fieldType = field.type;
@@ -373,14 +639,14 @@ function buildActivityUpdate(args, context) {
             // Skip validation for 'activitylink' and other field types
         }
         if (invalidUsers.length > 0) {
-            throw new Error(`Invalid user IDs in user fields: ${invalidUsers.join(", ")}. Use search_workspace_users to find valid user IDs.`);
+            throw new Error(`Invalid user IDs in user fields: ${invalidUsers.join(', ')}. Use search_workspace_users to find valid user IDs.`);
         }
     }
     return {
         _id: args.activityId,
         ...(args.name && { name: args.name }),
         ...(parsedFields &&
-            typeof parsedFields === "object" && {
+            typeof parsedFields === 'object' && {
             fields: parsedFields,
         }),
         ...(args.phaseId && { phaseId: args.phaseId }),
@@ -391,43 +657,165 @@ function buildActivityUpdate(args, context) {
  */
 function formatUpdateActivityResponse(args, result) {
     const changesText = [
-        args.name ? `- Name: "${args.name}"` : "",
-        args.fields ? `- Fields: ${JSON.stringify(args.fields, null, 2)}` : "",
-        args.phaseId ? `- Moved to phase: ${args.phaseId}` : "",
+        args.name ? `- Name: "${args.name}"` : '',
+        args.fields ? `- Fields: ${JSON.stringify(args.fields, null, 2)}` : '',
+        args.phaseId ? `- Moved to phase: ${args.phaseId}` : '',
     ]
         .filter(Boolean)
-        .join("\n");
+        .join('\n');
     const responseText = `✅ Successfully updated activity ${args.activityId}!\n\n📝 Changes applied:\n${changesText}\n\n💡 The activity has been updated in your Hailer workspace.\n\nAPI Response:\n${JSON.stringify(result, null, 2)}`;
     return {
         content: [
             {
-                type: "text",
+                type: 'text',
                 text: responseText,
             },
         ],
     };
 }
+/**
+ * Resolves a workflow's field definitions from the cached core.init. Lets
+ * update_activity validate field keys with zero per-activity server reads
+ * when the caller supplies workflowId.
+ */
+function resolveKnownWorkflowFields(workflowId, context) {
+    if (!workflowId) {
+        return undefined;
+    }
+    const workflow = context.init.processes?.find((proc) => proc._id === workflowId || proc.key === workflowId);
+    return workflow?.fields;
+}
+/** Bulk-mode body of update_activity — extracted so the per-item field-key validation keeps flat control flow. */
+async function executeBulkUpdate(activities, context, workflowId) {
+    logger.debug('Bulk update mode', {
+        activityCount: activities.length,
+        activities: JSON.stringify(activities, null, 2)
+    });
+    // Auto-fix common parameter name mistakes
+    for (const activity of activities) {
+        // Fix activityId -> _id
+        if (!activity._id && activity.activityId) {
+            logger.warn('Auto-fixing: activityId -> _id', { activityId: activity.activityId });
+            activity._id = activity.activityId;
+            delete activity.activityId;
+        }
+        // Fix fieldsAndValues -> fields
+        if (!activity.fields && activity.fieldsAndValues) {
+            logger.warn('Auto-fixing: fieldsAndValues -> fields', { activityId: activity._id });
+            activity.fields = activity.fieldsAndValues;
+            delete activity.fieldsAndValues;
+        }
+    }
+    // Validate that all activities have _id
+    const invalidActivities = activities.filter((act) => !act._id || typeof act._id !== 'string' || act._id.length < 24);
+    if (invalidActivities.length > 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ **Error: Invalid bulk update request**\n\nEach activity in the "activities" array MUST have a valid "_id" field (24-character activity ID).\n\n**What you sent:** ${JSON.stringify(activities, null, 2)}\n\n**Correct format:**\n\`\`\`json\n{\n  "activities": [\n    { "_id": "691ffe654217e9e8434e577c", "fields": { "fieldId": "value" } },\n    { "_id": "691ffe654217e9e8434e5774", "name": "New Name" }\n  ]\n}\n\`\`\`\n\n**Tip:** First use list_activities to get the activity IDs, then pass them in the _id field.`,
+                }],
+        };
+    }
+    // Build updates for each activity
+    const updates = activities.map((activity) => {
+        const activityUpdate = { _id: activity._id };
+        if (activity.name) {
+            activityUpdate.name = activity.name;
+        }
+        if (activity.fields) {
+            // Parse fields if string
+            const parsedFields = typeof activity.fields === 'string'
+                ? JSON.parse(activity.fields)
+                : activity.fields;
+            // Auto-fix activitylink fields: if LLM passes object with _id, extract just the ID
+            const linkFixEntries = parsedFields && typeof parsedFields === 'object'
+                ? Object.entries(parsedFields)
+                : [];
+            for (const [fieldId, fieldValue] of linkFixEntries) {
+                const isLinkObject = Boolean(fieldValue) &&
+                    typeof fieldValue === 'object' &&
+                    !Array.isArray(fieldValue) &&
+                    '_id' in fieldValue &&
+                    typeof fieldValue._id === 'string';
+                if (!isLinkObject) {
+                    continue;
+                }
+                logger.warn('Auto-fixing activitylink field in bulk mode', {
+                    activityId: activity._id,
+                    fieldId,
+                    extracted: fieldValue._id,
+                });
+                parsedFields[fieldId] = fieldValue._id;
+            }
+            autoFixDateFields(parsedFields, context);
+            activityUpdate.fields = parsedFields;
+        }
+        return activityUpdate;
+    });
+    // Per-item field-key validation — runs AFTER the auto-fixups above
+    // (values only, keys unchanged; see validateFieldKeys). Unknown keys silently
+    // no-op server-side, so this is the only guard against lost updates. With
+    // workflowId the field defs come from the cached init (zero server reads);
+    // without it the per-activity workflow lookups run in parallel — the old
+    // sequential awaits made bulk updates cost one round trip per activity.
+    const knownWorkflowFields = resolveKnownWorkflowFields(workflowId, context);
+    // Without workflowId each validation fetches its activity — bound the fan-out
+    // so a 2000-item bulk update can't fire 2000 concurrent backend reads. With
+    // workflowId the validation is pure CPU and runs in one batch.
+    const validationConcurrency = knownWorkflowFields ? updates.length : BULK_CONCURRENCY;
+    let keyError;
+    for (let start = 0; start < updates.length && !keyError; start += validationConcurrency) {
+        const chunk = updates.slice(start, start + validationConcurrency);
+        const chunkErrors = await Promise.all(chunk.map((update) => update.fields
+            ? validateUpdateFieldKeys(update._id, update.fields, context, knownWorkflowFields)
+            : undefined));
+        keyError = chunkErrors.find(Boolean);
+    }
+    if (keyError) {
+        return {
+            content: [{ type: 'text', text: keyError }],
+        };
+    }
+    // Collect unique phase IDs (most activities will have the same phase)
+    const phaseIds = activities
+        .map((act) => act.phaseId)
+        .filter((pid) => pid);
+    const commonPhaseId = phaseIds.length > 0 ? phaseIds[0] : undefined;
+    // Call API with all updates
+    const options = commonPhaseId ? { phaseId: commonPhaseId } : undefined;
+    await context.hailer.updateActivities(updates, options);
+    // Format bulk response
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `🎉 Successfully updated ${activities.length} activities!\n\n📊 **Bulk Update Summary:**\n- **Total Updated**: ${activities.length} activities\n- **Status**: All activities updated successfully\n\n✅ All activities have been updated in your Hailer workspace!`,
+            },
+        ],
+    };
+}
 const listActivitiesDescription = `List activities (items/records/tasks) from a workflow phase.
 
 **Prerequisites:** You need workflowId, phaseId, and field IDs. Get them via:
-1. \`list_workflows_minimal\` → workflowId
-2. \`list_workflow_phases\` → phaseId
-3. \`get_workflow_schema\` → field IDs for the \`fields\` parameter
+1. \`describe_workflows\` → workflowId
+2. \`describe_workflows\` with include: ['phases'] → phaseId
+3. \`describe_workflows\` with include: ['schema'] → field IDs for the \`fields\` parameter
 
 **Required params:** workflowId, phaseId, fields[] (array of field IDs to return)
 
-**Example flow:** User says "show my tasks" →
-1. list_workflows_minimal → find "Tasks" workflow
-2. list_workflow_phases → find "Open" phase
-3. get_workflow_schema → get field IDs
-4. list_activities with those IDs`;
+**Fast path:** \`countOnly: true\` returns only the workflow's total activity count (O(1), needs just workflowId — no phaseId/fields).
+
+**Large reads:** \`maxRecords\` (≤5000) fetches the whole result set in ONE call — pages are pulled in parallel server-side. Use 2-3 \`fields\` to stay under the response size cap. For counts, sums, group-bys, or cross-workflow joins prefer \`run_insight\` (SQL) where available — aggregates beat raw rows.`;
 exports.listActivitiesTool = {
     name: 'list_activities',
     group: tool_registry_1.ToolGroup.READ,
     description: listActivitiesDescription,
     schema: zod_1.z.object({
-        workflowId: zod_1.z.string().describe("Workflow ID or key to list activities from"),
-        phaseId: zod_1.z.string().describe("Phase ID or key to filter activities (required - use list_workflow_phases to get available phases)"),
+        workflowId: zod_1.z.string().describe('Workflow ID or key to list activities from'),
+        phaseId: zod_1.z.string().optional()
+            .describe("Phase ID or key to filter activities. Required unless countOnly=true. Use describe_workflows with include: ['phases'] for phases"),
+        countOnly: zod_1.z.coerce.boolean().optional().default(false).describe('Fast path: return only the total activity count for the workflow (O(1) v3.activity.count). ' +
+            'Needs just workflowId; phaseId/fields/filters are ignored.'),
         fields: zod_1.z.preprocess((val) => {
             if (typeof val === 'string') {
                 try {
@@ -440,31 +828,37 @@ exports.listActivitiesTool = {
                 }
             }
             return val;
-        }, zod_1.z.array(zod_1.z.string()).optional()).describe("Array of field IDs or keys to return (use get_workflow_schema to see available fields). Select the fields needed for the task - use fewer fields for listings (name, status, etc.) and more fields when detailed information is required. If not provided, you must call get_workflow_schema first."),
+        }, zod_1.z.array(zod_1.z.string()).optional()).describe("Array of field IDs or keys to return (use describe_workflows with include: ['schema'] to see available fields). Select the fields needed for the task - use fewer fields for listings (name, status, etc.) and more fields when detailed information is required."),
         filters: zod_1.z.record(zod_1.z.object({
             operator: zod_1.z.enum([
-                "text_search",
-                "equals",
-                "not_equals",
-                "contains",
-                "greater_than",
-                "greater_than_or_equal",
-                "less_than",
-                "less_than_or_equal",
-                "range",
-            ]).describe("Filter operator: text_search for partial text match in field (BEST for filtering by text in relationship fields when you only have a name), equals for exact match (requires activity ID), range for date/number ranges, contains for partial text, comparison operators for numbers/dates"),
-            value: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional().describe("Value to filter by - REQUIRED for text_search, equals, not_equals, contains, greater_than, less_than operators. NOT USED for range operator (use start/end instead). For text_search: use the text/name to search for. For equals: use the entity ID."),
+                'text_search',
+                'equals',
+                'not_equals',
+                'contains',
+                'greater_than',
+                'greater_than_or_equal',
+                'less_than',
+                'less_than_or_equal',
+                'range',
+            ]).describe('Filter operator: text_search for partial text match in field (BEST for filtering by text in relationship fields when you only have a name), equals for exact match (requires activity ID), range for date/number ranges, contains for partial text, comparison operators for numbers/dates'),
+            value: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional().describe('Value to filter by - REQUIRED for text_search, equals, not_equals, contains, greater_than, less_than operators. NOT USED for range operator (use start/end instead). For text_search: use the text/name to search for. For equals: use the entity ID.'),
             start: zod_1.z.coerce.number().optional().describe("Start value - ONLY for range operator (NOT in 'value' field). Unix timestamp in milliseconds for date ranges. NOT nested in 'value'."),
             end: zod_1.z.coerce.number().optional().describe("End value - ONLY for range operator (NOT in 'value' field). Unix timestamp in milliseconds for date ranges. Example: for June 2025 date range, use end=1719791999000 directly here, NOT nested in 'value'."),
         })).optional().describe("Filter by field values. STRUCTURE: {\"fieldId\": {\"operator\": \"...\", \"value\": \"...\"}}. EXAMPLE: To find player named 'Harry Kane', use: {\"691ffdf84217e9e8434e5694\": {\"operator\": \"text_search\", \"value\": \"Harry Kane\"}}. WRONG: {\"playerName\": \"Harry Kane\"} or {\"fieldId\": \"Harry Kane\"}. Operators: text_search (partial text match), equals (exact ID match), range (use start/end instead of value)."),
-        search: zod_1.z.string().optional().describe("Text search across activity content - USE FILTERS INSTEAD when possible for reliable results. Only use search for truly exploratory queries."),
-        limit: zod_1.z.coerce.number().optional().default(50).describe("Maximum number of activities to return (default: 50, max: 20000)"),
-        page: zod_1.z.coerce.number().optional().default(0).describe("Page number for pagination (0-based)"),
-        sortBy: zod_1.z.enum(["name", "created", "updated", "priority"]).optional().default("updated").describe("Field to sort by"),
-        sortOrder: zod_1.z.enum(["asc", "desc"]).optional().default("desc").describe("Sort direction"),
-        includeStats: zod_1.z.coerce.boolean().optional().default(true).describe("Include total count and pagination metadata"),
+        search: zod_1.z.string().optional().describe('Text search across activity content - USE FILTERS INSTEAD when possible for reliable results. Only use search for truly exploratory queries.'),
+        limit: zod_1.z.coerce.number().int().min(1).max(200).optional().default(50).describe('Activities per page (default: 50, max: 200 — the server silently returns empty results for larger values; paginate with `page` instead)'),
+        page: zod_1.z.coerce.number().int().min(0).optional().default(0).describe('Page number for pagination (0-based). The response reports the total page count'),
+        maxRecords: zod_1.z.coerce.number().int().min(1).max(5000).optional().describe('BULK READ: fetch up to this many matching activities in ONE call — pages are pulled in parallel server-side ' +
+            '(sorted created asc). Overrides limit/page. Keep fields minimal (2-3): the response size cap still applies'),
+        sortBy: zod_1.z.enum(['name', 'created', 'updated', 'priority']).optional().default('updated').describe('Field to sort by'),
+        sortOrder: zod_1.z.enum(['asc', 'desc']).optional().default('desc').describe('Sort direction'),
+        includeStats: zod_1.z.coerce.boolean().optional().default(false).describe('Include schedule/value stats metadata (the total count is always returned regardless)'),
     }),
     async execute(args, context) {
+        // countOnly fast path — dispatches to the retired count_activities body (own error handling)
+        if (args.countOnly) {
+            return executeActivityCount(args.workflowId, context);
+        }
         try {
             const workflow = validateAndGetWorkflow(args.workflowId, context.init);
             const phaseId = await resolvePhaseForListing(workflow, args, context.init);
@@ -472,10 +866,10 @@ exports.listActivitiesTool = {
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: `❌ **Fields parameter required**: You must specify which fields to return to avoid huge responses.\n\n` +
                                 `📋 **Next steps:**\n` +
-                                `1. Call \`get_workflow_schema\` with workflowId: "${args.workflowId}" and phaseId: "${phaseId}" to see available fields\n` +
+                                `1. Call \`describe_workflows\` with workflowId: "${args.workflowId}" and include: ['schema'] to see available fields\n` +
                                 `2. Then call \`list_activities\` again with 2-3 essential field IDs\n\n` +
                                 `💡 **Best practices:**\n` +
                                 `- For product listings: ["name", "price", "stock"] (3 fields)\n` +
@@ -502,10 +896,10 @@ exports.listActivitiesTool = {
                     return {
                         content: [
                             {
-                                type: "text",
+                                type: 'text',
                                 text: `❌ **Filter Error:** ${filterErrorMessage}\n\n` +
                                     `💡 **Valid operators:** equals, not_equals, contains, text_search, greater_than, less_than, range\n` +
-                                    `📋 Call \`get_workflow_schema\` to see available field IDs and types`,
+                                    `📋 Call \`describe_workflows\` with include: ['schema'] to see available field IDs and types`,
                             }
                         ],
                     };
@@ -515,6 +909,9 @@ exports.listActivitiesTool = {
                     apiFilters: JSON.stringify(apiFilters)
                 });
             }
+            if (args.maxRecords) {
+                return await executeBulkRead(args, workflow, phaseId, apiFilters, context);
+            }
             const options = {
                 page: args.page,
                 search: args.search,
@@ -542,12 +939,13 @@ exports.listActivitiesTool = {
             return response;
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Failed to list activities", error);
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Failed to list activities', error);
+            }
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: `❌ Failed to list activities: ${(0, tool_helpers_1.extractErrorMessage)(error)}`,
                     },
                 ],
@@ -567,37 +965,38 @@ exports.showActivityByIdTool = {
     group: tool_registry_1.ToolGroup.READ,
     description: showActivityByIdDescription,
     schema: zod_1.z.object({
-        activityId: zod_1.z.string().describe("Activity ID to load"),
+        activityId: zod_1.z.string().describe('Activity ID to load'),
     }),
     async execute(args, context) {
         // Validate: reject known non-activity ID patterns
         const id = args.activityId;
         if (!id || typeof id !== 'string' || id.length < 24) {
             return {
-                content: [{ type: "text", text: `❌ Invalid activity ID: "${id}". Activity IDs are 24-character hex strings from list_activities results. Do NOT use workflow IDs, field IDs, phase IDs, or discussion IDs.` }],
+                content: [{ type: 'text', text: `❌ Invalid activity ID: "${id}". Activity IDs are 24-character hex strings from list_activities results. Do NOT use workflow IDs, field IDs, phase IDs, or discussion IDs.` }],
             };
         }
         try {
             const activity = await context.hailer.fetchActivityById(args.activityId);
-            let responseText = `✅ Loaded activity with ID "${activity._id}":\n\n${JSON.stringify(activity, null, 2)}`;
+            const responseText = `✅ Loaded activity with ID "${activity._id}":\n\n${JSON.stringify(activity, null, 2)}`;
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: responseText,
                     },
                 ],
             };
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Failed to load activity", error, {
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Failed to load activity', error, {
                     activityId: args.activityId,
                 });
+            }
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: `❌ Failed to load activity "${args.activityId}": ${(0, tool_helpers_1.extractErrorMessage)(error)}\n\n⚠️ Make sure this is an ACTIVITY ID (from list_activities or activity._id), NOT a workflow ID, field ID, phase ID, or discussion ID.`,
                     },
                 ],
@@ -610,10 +1009,10 @@ exports.showActivityByIdTool = {
 // ============================================================================
 const createActivityDescription = `Create a new activity (item/record/task) in a workflow.
 
-**Prerequisites:** Get IDs first via:
-1. \`list_workflows_minimal\` → workflowId
-2. \`list_workflow_phases\` → phaseId (use isInitial=true phase)
-3. \`get_workflow_schema\` → field IDs for the fields parameter
+**Prerequisites:** Get IDs first via \`describe_workflows\`:
+1. No args → workflowId
+2. include: ['phases'] → phaseId (use isInitial=true phase)
+3. include: ['schema'] → field IDs for the fields parameter
 
 **Required:** workflowId + (name OR activities[])
 **Recommended:** phaseId (defaults to initial phase if omitted)
@@ -633,38 +1032,38 @@ exports.createActivityTool = {
     schema: zod_1.z.object({
         workflowId: zod_1.z
             .string()
-            .describe("The workflow ID or key where to create the activity/activities. Find this in any list_* tool results"),
+            .describe('The workflow ID or key where to create the activity/activities. Find this in any list_* tool results'),
         // BULK CREATION (optional - takes precedence over single parameters)
         activities: zod_1.z
             .array(zod_1.z.object({
-            name: zod_1.z.string().min(1, "Activity name cannot be empty").describe("Activity name/title"),
-            fields: zod_1.z.union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()]).optional().describe("Custom field values (field keys or IDs)"),
-            phaseId: zod_1.z.string().optional().describe("Phase ID or key for this activity"),
-            teamId: zod_1.z.string().optional().describe("Team ID for this activity"),
-            discussionId: zod_1.z.string().optional().describe("Link to existing discussion"),
-            followerIds: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional().describe("User IDs to invite"),
-            fileIds: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional().describe("File IDs to attach"),
+            name: zod_1.z.string().min(1, 'Activity name cannot be empty').describe('Activity name/title'),
+            fields: zod_1.z.union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()]).optional().describe('Custom field values (field keys or IDs)'),
+            phaseId: zod_1.z.string().optional().describe('Phase ID or key for this activity'),
+            teamId: zod_1.z.string().optional().describe('Team ID for this activity'),
+            discussionId: zod_1.z.string().optional().describe('Link to existing discussion'),
+            followerIds: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional().describe('User IDs to invite'),
+            fileIds: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional().describe('File IDs to attach'),
         }))
             .optional()
-            .describe("BULK: Array of activities. Example: [{\"name\": \"Task 1\", \"fields\": {...}}, {\"name\": \"Task 2\"}]. If provided, single parameters are ignored."),
+            .describe('BULK: Array of activities. Example: [{"name": "Task 1", "fields": {...}}, {"name": "Task 2"}]. If provided, single parameters are ignored.'),
         // SINGLE CREATION (used when 'activities' is not provided)
         name: zod_1.z
             .string()
-            .min(1, "Activity name cannot be empty")
+            .min(1, 'Activity name cannot be empty')
             .optional()
             .describe("SINGLE: The activity name/title (e.g. '🤖 AI Analysis Bot', 'Customer Research Task')"),
         description: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional detailed description"),
+            .describe('SINGLE: Optional detailed description'),
         phaseId: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional phase/category ID or key. If not specified, uses the default phase"),
+            .describe('SINGLE: Optional phase/category ID or key. If not specified, uses the default phase'),
         teamId: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional team ID for team-specific activities"),
+            .describe('SINGLE: Optional team ID for team-specific activities'),
         fields: zod_1.z
             .union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()])
             .optional()
@@ -672,20 +1071,20 @@ exports.createActivityTool = {
         discussionId: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional discussion ID to link to existing conversation"),
+            .describe('SINGLE: Optional discussion ID to link to existing conversation'),
         followerIds: zod_1.z
             .union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()])
             .optional()
-            .describe("SINGLE: Optional array of user IDs to invite"),
+            .describe('SINGLE: Optional array of user IDs to invite'),
         fileIds: zod_1.z
             .union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()])
             .optional()
-            .describe("SINGLE: Optional array of file IDs to attach"),
+            .describe('SINGLE: Optional array of file IDs to attach'),
     }),
     async execute(args, context) {
         try {
             // DEBUG: Log raw input to diagnose LLM tool calling issues
-            logger.debug("create_activity called", {
+            logger.debug('create_activity called', {
                 hasName: !!args.name,
                 hasActivities: !!args.activities,
                 activitiesType: typeof args.activities,
@@ -701,7 +1100,7 @@ exports.createActivityTool = {
                 };
                 if (activityData.fields) {
                     let parsedFields = activityData.fields;
-                    if (typeof activityData.fields === "string" && activityData.fields.trim() !== "") {
+                    if (typeof activityData.fields === 'string' && activityData.fields.trim() !== '') {
                         try {
                             parsedFields = JSON.parse(activityData.fields);
                         }
@@ -710,22 +1109,22 @@ exports.createActivityTool = {
                         }
                     }
                     if (parsedFields &&
-                        typeof parsedFields === "object" &&
+                        typeof parsedFields === 'object' &&
                         Object.keys(parsedFields).length > 0) {
                         autoFixDateFields(parsedFields, context);
                         activity.fields = parsedFields;
                     }
                 }
-                if (activityData.phaseId && activityData.phaseId.trim() !== "") {
+                if (activityData.phaseId && activityData.phaseId.trim() !== '') {
                     activity.phaseId = activityData.phaseId;
                 }
-                if (activityData.teamId && activityData.teamId.trim() !== "") {
+                if (activityData.teamId && activityData.teamId.trim() !== '') {
                     activity.teamId = activityData.teamId;
                 }
                 if (activityData.followerIds) {
                     let parsedFollowerIds = activityData.followerIds;
-                    if (typeof activityData.followerIds === "string" &&
-                        activityData.followerIds.trim() !== "") {
+                    if (typeof activityData.followerIds === 'string' &&
+                        activityData.followerIds.trim() !== '') {
                         try {
                             parsedFollowerIds = JSON.parse(activityData.followerIds);
                         }
@@ -744,7 +1143,7 @@ exports.createActivityTool = {
                                 }
                             }
                             if (invalidUsers.length > 0) {
-                                throw new Error(`Invalid user IDs in followerIds: ${invalidUsers.join(", ")}. Use search_workspace_users to find valid user IDs.`);
+                                throw new Error(`Invalid user IDs in followerIds: ${invalidUsers.join(', ')}. Use search_workspace_users to find valid user IDs.`);
                             }
                         }
                         activity.followerIds = parsedFollowerIds;
@@ -752,8 +1151,8 @@ exports.createActivityTool = {
                 }
                 if (activityData.fileIds) {
                     let parsedFileIds = activityData.fileIds;
-                    if (typeof activityData.fileIds === "string" &&
-                        activityData.fileIds.trim() !== "") {
+                    if (typeof activityData.fileIds === 'string' &&
+                        activityData.fileIds.trim() !== '') {
                         try {
                             parsedFileIds = JSON.parse(activityData.fileIds);
                         }
@@ -791,7 +1190,7 @@ exports.createActivityTool = {
                 }
             }
             let activitiesToCreate;
-            let options = {
+            const options = {
                 returnDocument: true,
             };
             if (isBulk) {
@@ -810,7 +1209,7 @@ exports.createActivityTool = {
                     return activity;
                 });
                 // Check for common discussionId in bulk
-                if (args.discussionId && args.discussionId.trim() !== "") {
+                if (args.discussionId && args.discussionId.trim() !== '') {
                     options.discussionId = args.discussionId;
                 }
             }
@@ -819,7 +1218,7 @@ exports.createActivityTool = {
                 if (!args.name) {
                     throw new Error("Either 'activities' array or 'name' parameter is required");
                 }
-                logger.debug("Creating single activity", {
+                logger.debug('Creating single activity', {
                     workflowId: args.workflowId,
                     name: args.name,
                     defaultTeamId: defaultTeamId,
@@ -830,12 +1229,29 @@ exports.createActivityTool = {
                     activity.teamId = defaultTeamId;
                 }
                 activitiesToCreate = [activity];
-                if (args.discussionId && args.discussionId.trim() !== "") {
+                if (args.discussionId && args.discussionId.trim() !== '') {
                     options.discussionId = args.discussionId;
                 }
             }
+            // Pre-validate field keys before API call — runs AFTER processActivity's
+            // auto-fixups (values only, keys unchanged; see validateFieldKeys).
+            // Unknown keys (e.g. field NAMES) silently no-op server-side.
+            const workflow = context.init.processes?.find((proc) => proc._id === args.workflowId);
+            const workflowFieldDefs = workflow?.fields;
+            for (let i = 0; i < activitiesToCreate.length; i++) {
+                const item = activitiesToCreate[i];
+                const keyError = workflowFieldDefs && item.fields ? validateFieldKeys(item.fields, workflowFieldDefs) : undefined;
+                if (keyError) {
+                    const itemName = item.name || `Activity ${i + 1}`;
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `❌ Invalid field keys in "${itemName}" — nothing was created.\n\n${keyError}`,
+                            }],
+                    };
+                }
+            }
             // Pre-validate required fields before API call
-            const workflow = context.init.processes?.find((p) => p._id === args.workflowId);
             if (workflow?.fields) {
                 const requiredFields = [];
                 for (const [fieldId, field] of Object.entries(workflow.fields)) {
@@ -864,7 +1280,7 @@ exports.createActivityTool = {
                         const fieldList = requiredFields.map(f => `- ${f.label} (key: ${f.key}, id: ${f.id})`).join('\n');
                         return {
                             content: [{
-                                    type: "text",
+                                    type: 'text',
                                     text: `❌ Missing required fields - cannot create activities.\n\n**Required fields for this workflow:**\n${fieldList}\n\n**Activities with missing fields:**\n${missingByActivity.map(m => `- ${m}`).join('\n')}\n\n💡 Add the missing fields to each activity's \`fields\` object using either the field key or ID.`,
                                 }],
                         };
@@ -891,7 +1307,7 @@ exports.createActivityTool = {
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: responseText,
                         },
                     ],
@@ -922,7 +1338,7 @@ exports.createActivityTool = {
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: responseText,
                         },
                     ],
@@ -930,11 +1346,12 @@ exports.createActivityTool = {
             }
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Failed to create activity/activities", error, {
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Failed to create activity/activities', error, {
                     workflowId: args.workflowId,
                     isBulk: !!(args.activities && args.activities.length > 0),
                 });
+            }
             const errorMessage = error instanceof Error
                 ? error.message
                 : (typeof error === 'object' && error !== null)
@@ -943,7 +1360,7 @@ exports.createActivityTool = {
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: `❌ Error creating activity: ${errorMessage}\n\n💡 Troubleshooting Tips:\n- Verify the workflowId exists and is accessible\n- Check that you have permission to create activities in this workflow\n- Ensure field IDs in the fields object match the workflow's field definitions\n- Use search_workspace_users to find valid user IDs for assignment\n- Verify user IDs in followerIds exist and are accessible`,
                     },
                 ],
@@ -956,10 +1373,11 @@ exports.createActivityTool = {
 // ============================================================================
 const updateActivityDescription = `Update an existing activity - change fields or move to different phase.
 
-**To update fields:** Get field IDs from \`get_workflow_schema\` first, then pass them in the fields object.
-**To change phase:** Get phase IDs from \`list_workflow_phases\`, pass target phaseId.
+**To update fields:** Get field IDs from \`describe_workflows\` (include: ['schema']) first, then pass them in the fields object.
+**To change phase:** Get phase IDs from \`describe_workflows\` (include: ['phases']), pass target phaseId.
 
 **Required:** activityId (for single) OR activities[] array (for bulk)
+**Performance:** Pass \`workflowId\` whenever you know it (you usually do — it came from list_activities). It skips a per-activity server read used for field-key validation; on bulk updates that is one read per activity saved.
 
 **Field value formats:**
 - Text: \`"value"\`
@@ -976,9 +1394,9 @@ exports.updateActivityTool = {
     schema: zod_1.z.object({
         // BULK: Array of activities to update
         activities: zod_1.z
-            .preprocess((val) => (typeof val === "string" ? JSON.parse(val) : val), zod_1.z
+            .preprocess((val) => (typeof val === 'string' ? JSON.parse(val) : val), zod_1.z
             .array(zod_1.z.object({
-            _id: zod_1.z.string().min(24, "Activity ID must be at least 24 characters"),
+            _id: zod_1.z.string().min(24, 'Activity ID must be at least 24 characters'),
             name: zod_1.z.string().optional(),
             fields: zod_1.z.record(zod_1.z.any()).optional(),
             phaseId: zod_1.z.string().optional(),
@@ -989,10 +1407,10 @@ exports.updateActivityTool = {
         // SINGLE: Individual activity parameters
         activityId: zod_1.z
             .string()
-            .min(24, "Activity ID must be at least 24 characters")
+            .min(24, 'Activity ID must be at least 24 characters')
             .optional()
-            .describe("SINGLE: The unique ID of the activity to update (works for any workflow)"),
-        name: zod_1.z.string().optional().describe("SINGLE: New activity title/name"),
+            .describe('SINGLE: The unique ID of the activity to update (works for any workflow)'),
+        name: zod_1.z.string().optional().describe('SINGLE: New activity title/name'),
         fields: zod_1.z
             .union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()])
             .optional()
@@ -1000,97 +1418,24 @@ exports.updateActivityTool = {
         phaseId: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional phase ID or key to move the activity to"),
+            .describe('SINGLE: Optional phase ID or key to move the activity to'),
+        workflowId: zod_1.z
+            .string()
+            .optional()
+            .describe('Workflow ID or key the activities belong to (single AND bulk). Strongly recommended when known: skips one validation read per activity'),
     }),
     async execute(args, context) {
         try {
             // BULK MODE: Update multiple activities
             if (args.activities && Array.isArray(args.activities)) {
-                logger.debug("Bulk update mode", {
-                    activityCount: args.activities.length,
-                    activities: JSON.stringify(args.activities, null, 2)
-                });
-                // Auto-fix common parameter name mistakes
-                for (const activity of args.activities) {
-                    // Fix activityId -> _id
-                    if (!activity._id && activity.activityId) {
-                        logger.warn("Auto-fixing: activityId -> _id", { activityId: activity.activityId });
-                        activity._id = activity.activityId;
-                        delete activity.activityId;
-                    }
-                    // Fix fieldsAndValues -> fields
-                    if (!activity.fields && activity.fieldsAndValues) {
-                        logger.warn("Auto-fixing: fieldsAndValues -> fields", { activityId: activity._id });
-                        activity.fields = activity.fieldsAndValues;
-                        delete activity.fieldsAndValues;
-                    }
-                }
-                // Validate that all activities have _id
-                const invalidActivities = args.activities.filter((a) => !a._id || typeof a._id !== 'string' || a._id.length < 24);
-                if (invalidActivities.length > 0) {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: `❌ **Error: Invalid bulk update request**\n\nEach activity in the "activities" array MUST have a valid "_id" field (24-character activity ID).\n\n**What you sent:** ${JSON.stringify(args.activities, null, 2)}\n\n**Correct format:**\n\`\`\`json\n{\n  "activities": [\n    { "_id": "691ffe654217e9e8434e577c", "fields": { "fieldId": "value" } },\n    { "_id": "691ffe654217e9e8434e5774", "name": "New Name" }\n  ]\n}\n\`\`\`\n\n**Tip:** First use list_activities to get the activity IDs, then pass them in the _id field.`,
-                            }],
-                    };
-                }
-                // Build updates for each activity
-                const updates = args.activities.map((activity) => {
-                    const activityUpdate = { _id: activity._id };
-                    if (activity.name)
-                        activityUpdate.name = activity.name;
-                    if (activity.fields) {
-                        // Parse fields if string
-                        let parsedFields = typeof activity.fields === 'string'
-                            ? JSON.parse(activity.fields)
-                            : activity.fields;
-                        // Auto-fix activitylink fields: if LLM passes object with _id, extract just the ID
-                        if (parsedFields && typeof parsedFields === "object") {
-                            for (const [fieldId, fieldValue] of Object.entries(parsedFields)) {
-                                if (fieldValue &&
-                                    typeof fieldValue === "object" &&
-                                    !Array.isArray(fieldValue) &&
-                                    "_id" in fieldValue &&
-                                    typeof fieldValue._id === "string") {
-                                    logger.warn("Auto-fixing activitylink field in bulk mode", {
-                                        activityId: activity._id,
-                                        fieldId,
-                                        extracted: fieldValue._id,
-                                    });
-                                    parsedFields[fieldId] = fieldValue._id;
-                                }
-                            }
-                        }
-                        autoFixDateFields(parsedFields, context);
-                        activityUpdate.fields = parsedFields;
-                    }
-                    return activityUpdate;
-                });
-                // Collect unique phase IDs (most activities will have the same phase)
-                const phaseIds = args.activities
-                    .map((a) => a.phaseId)
-                    .filter((p) => p);
-                const commonPhaseId = phaseIds.length > 0 ? phaseIds[0] : undefined;
-                // Call API with all updates
-                const options = commonPhaseId ? { phaseId: commonPhaseId } : undefined;
-                await context.hailer.updateActivities(updates, options);
-                // Format bulk response
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `🎉 Successfully updated ${args.activities.length} activities!\n\n📊 **Bulk Update Summary:**\n- **Total Updated**: ${args.activities.length} activities\n- **Status**: All activities updated successfully\n\n✅ All activities have been updated in your Hailer workspace!`,
-                        },
-                    ],
-                };
+                return await executeBulkUpdate(args.activities, context, args.workflowId);
             }
             // SINGLE MODE: Update one activity
             // Validate activityId is provided for single mode
             if (!args.activityId || typeof args.activityId !== 'string' || args.activityId.length < 24) {
                 return {
                     content: [{
-                            type: "text",
+                            type: 'text',
                             text: `❌ **Error: Missing or invalid activityId**\n\nFor single activity updates, you must provide a valid "activityId" (24-character hex string).\n\n**What you sent:** activityId = ${JSON.stringify(args.activityId)}\n\n**Correct format:**\n\`\`\`json\n{\n  "activityId": "691ffe654217e9e8434e577c",\n  "name": "New Name",\n  "fields": { "fieldId": "value" }\n}\n\`\`\`\n\n**For bulk updates (3+ activities), use:**\n\`\`\`json\n{\n  "activities": [\n    { "_id": "activity-id-1", "fields": {...} },\n    { "_id": "activity-id-2", "name": "New Name" }\n  ]\n}\n\`\`\`\n\n**Tip:** Use list_activities or show_activity_by_id to find activity IDs first.`,
                         }],
                 };
@@ -1099,32 +1444,44 @@ exports.updateActivityTool = {
             if (!args.name && !args.fields && !args.phaseId) {
                 return {
                     content: [{
-                            type: "text",
+                            type: 'text',
                             text: `❌ **Error: No update data provided**\n\nYou called update_activity with activityId="${args.activityId}" but didn't provide any data to update.\n\n**You must provide at least one of:**\n- "name" - to update the activity name\n- "fields" - to update field values\n- "phaseId" - to move to a different phase\n\n**Example:**\n\`\`\`json\n{\n  "activityId": "${args.activityId}",\n  "fields": {\n    "fieldId123": "new value"\n  }\n}\n\`\`\``,
                         }],
                 };
             }
-            logger.debug("Single update mode", {
+            logger.debug('Single update mode', {
                 activityId: args.activityId,
                 name: args.name,
                 fields: JSON.stringify(args.fields, null, 2),
                 phaseId: args.phaseId
             });
             const updates = buildActivityUpdate(args, context);
+            // Field-key validation — runs AFTER buildActivityUpdate's auto-fixups
+            // (values only, keys unchanged; see validateFieldKeys), right before the
+            // API call. Unknown keys (e.g. field NAMES) silently no-op server-side.
+            const singleKeyError = updates.fields
+                ? await validateUpdateFieldKeys(args.activityId, updates.fields, context, resolveKnownWorkflowFields(args.workflowId, context))
+                : undefined;
+            if (singleKeyError) {
+                return {
+                    content: [{ type: 'text', text: singleKeyError }],
+                };
+            }
             const options = args.phaseId ? { phaseId: args.phaseId } : undefined;
             const result = await context.hailer.updateActivities([updates], options);
             return formatUpdateActivityResponse(args, result);
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Failed to update activity", error, {
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Failed to update activity', error, {
                     activityId: args.activityId || 'bulk',
                     activityCount: args.activities?.length,
                 });
+            }
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: `❌ Error updating ${args.activities ? 'activities' : 'activity'}: ${error instanceof Error ? error.message : String(error)}`,
                     },
                 ],