@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-3

package/dist/mcp/prompts.js

@@ -1027,11 +1027,10 @@ ${args.intents ? `**Intents**: ${args.intents}` : ""}
 
 ## Instructions
 
-### Step 1: Read Templates (Resources)
-Read these resources to get templates and reference data:
-- \`ema://templates/voice-ai/config\` - Voice AI persona configuration template
-- \`ema://templates/voice-ai/workflow-prompt\` - Auto Builder prompt template with safeguards
-- \`ema://templates/voice-ai/readme\` - Deployment guide template
+### Step 1: Get Templates
+Get templates from API or use generated fallbacks:
+- \`template(config="voice")\` - Voice AI persona configuration (API-first with fallback)
+- \`ema://catalog/persona-templates\` - Live API templates
 - \`ema://catalog/agents-summary\` - Available agents for workflow composition
 
 ### Step 2: Read Validation Rules (Resources)
@@ -1056,9 +1055,9 @@ Using the templates from Step 1 and guidance from Steps 3-4, generate:
 **Folder structure:**
 \`\`\`
 ${args.name.toLowerCase().replace(/\s+/g, "-")}/
-├── README.md              # Deployment guide (based on ema://templates/voice-ai/readme)
-├── workflow-prompt.md     # Auto Builder prompt (based on ema://templates/voice-ai/workflow-prompt)
-├── persona-config.json    # Voice settings (based on ema://templates/voice-ai/config)
+├── README.md              # Deployment guide
+├── workflow-prompt.md     # Auto Builder prompt
+├── persona-config.json    # Voice settings (from template(config="voice"))
 └── proto-config.json      # Full API config
 \`\`\`
 
@@ -1108,10 +1107,10 @@ ${args.data_sources ? `**Data Sources**: ${args.data_sources}` : ""}
 
 ## Instructions
 
-### Step 1: Read Templates (Resources)
-Read these resources to get templates and reference data:
-- \`ema://templates/chat-ai/config\` - Chat AI persona configuration template
-- \`ema://templates/chat-ai/readme\` - Deployment guide template
+### Step 1: Get Templates
+Get templates from API or use generated fallbacks:
+- \`template(config="chat")\` - Chat AI persona configuration (API-first with fallback)
+- \`ema://catalog/persona-templates\` - Live API templates
 - \`ema://catalog/agents-summary\` - Available agents for workflow composition
 - \`ema://catalog/patterns\` - Common workflow patterns
 
@@ -1134,9 +1133,9 @@ Using the templates from Step 1 and guidance from Steps 3-4, generate:
 **Folder structure:**
 \`\`\`
 ${args.name.toLowerCase().replace(/\s+/g, "-")}/
-├── README.md              # Deployment guide (based on ema://templates/chat-ai/readme)
+├── README.md              # Deployment guide
 ├── workflow-prompt.md     # Auto Builder prompt
-├── persona-config.json    # Chat settings (based on ema://templates/chat-ai/config)
+├── persona-config.json    # Chat settings (from template(config="chat"))
 └── docs/                  # Knowledge base documents
     └── _metadata.json
 \`\`\`

package/dist/mcp/resources.js

@@ -4,10 +4,13 @@
  * Provides static and file-backed resources for the Ema MCP Server.
  *
  * Resources are the canonical source of truth for:
- * - Templates: Persona configuration templates (voice, chat, dashboard)
- * - Agent Catalog: Dynamic list of available workflow agents
+ * - Agent Catalog: Dynamic list of available workflow agents + API templates
  * - Validation Rules: Input/output compatibility rules
  * - Documentation: User guides and references
+ * - Schemas: Action schemas and type definitions
+ *
+ * Note: File-backed templates (ema://templates/*) were removed.
+ * Use API templates via ema://catalog/persona-templates or template() tool.
  *
  * Why resources vs tools:
  * - Resources: Static/reference content the AI assistant reads to understand context
@@ -97,7 +100,7 @@ function hasPathTraversal(uriPath) {
 const RESOURCE_MAP = {
     // Core Documentation (files that exist in this repo)
     "ema://docs/getting-started": {
-        path: "resources/docs/getting-started.md",
+        path: "docs/mcp-tools-guide.md",
         description: "Quick start guide: first steps, key concepts, essential rules, common operations",
         mimeType: "text/markdown",
     },
@@ -116,42 +119,10 @@ const RESOURCE_MAP = {
         description: "MCP tools usage guide: tool categories, best practices, example call sequences, workflow review patterns",
         mimeType: "text/markdown",
     },
-    // Templates - Persona configuration templates
-    "ema://templates/voice-ai/config": {
-        path: "resources/templates/voice-ai/persona-config.json",
-        description: "Voice AI persona configuration template: voiceSettings, conversationSettings, vadSettings, dataProtection",
-        mimeType: "application/json",
-    },
-    "ema://templates/voice-ai/workflow-prompt": {
-        path: "resources/templates/voice-ai/workflow-prompt.md",
-        description: "Voice AI Auto Builder prompt template with node definitions, connections, and validation assertions",
-        mimeType: "text/markdown",
-    },
-    "ema://templates/voice-ai/readme": {
-        path: "resources/templates/voice-ai/README.md",
-        description: "Voice AI deployment guide: setup steps, testing checklist, maintenance procedures",
-        mimeType: "text/markdown",
-    },
-    "ema://templates/chat-ai/config": {
-        path: "resources/templates/chat-ai/persona-config.json",
-        description: "Chat AI persona configuration template: chatbotSdkConfig, feedbackMessage, fileUpload settings",
-        mimeType: "application/json",
-    },
-    "ema://templates/chat-ai/readme": {
-        path: "resources/templates/chat-ai/README.md",
-        description: "Chat AI deployment guide: workflow generation, widget configuration, knowledge base setup",
-        mimeType: "text/markdown",
-    },
-    "ema://templates/dashboard-ai/config": {
-        path: "resources/templates/dashboard-ai/persona-config.json",
-        description: "Dashboard AI persona configuration template: inputSchema, batchSettings, timeout configuration",
-        mimeType: "application/json",
-    },
-    "ema://templates/dashboard-ai/readme": {
-        path: "resources/templates/dashboard-ai/README.md",
-        description: "Dashboard AI deployment guide: batch processing setup, input configuration",
-        mimeType: "text/markdown",
-    },
+    // Templates - REMOVED (file-backed templates removed in favor of API + generated fallbacks)
+    // Use: client.getPersonaTemplates() for live API templates
+    // Use: getTemplateFallback("voice") from sdk/generated/template-fallbacks.ts for offline fallbacks
+    // See: ema://catalog/persona-templates for dynamic API-backed template listing
     // DEPRECATED: Use ema://docs/usage-guide (dynamic) instead
     // This static resource is kept for backwards compatibility but now generates from guidance module
 };
@@ -236,7 +207,7 @@ const DYNAMIC_RESOURCES = [
         mimeType: "application/json",
         generate: async () => JSON.stringify(OPTIMIZATION_RULES, null, 2),
     },
-    // Persona Templates - Dynamic from API
+    // Persona Templates - Dynamic from API with fallback
     {
         uri: "ema://catalog/templates",
         name: "catalog/templates",
@@ -244,7 +215,15 @@ const DYNAMIC_RESOURCES = [
         mimeType: "application/json",
         generate: async (ctx) => {
             const templates = await getDynamicPersonaTemplates({ env: ctx.env });
-            return JSON.stringify(templates.map(templateDtoToResource), null, 2);
+            if (templates.length > 0) {
+                return JSON.stringify(templates.map(templateDtoToResource), null, 2);
+            }
+            // Fallback when API unavailable - provide guidance
+            return JSON.stringify({
+                _note: "API templates unavailable. Use catalog(method='list', type='templates') tool which connects to API directly, or use template(config='voice|chat|dashboard') for config fallbacks.",
+                fallback_types: ["voice", "chat", "dashboard"],
+                how_to_get: "catalog(method='list', type='templates') or template(config='voice')",
+            }, null, 2);
         },
     },
     {
@@ -255,7 +234,28 @@ const DYNAMIC_RESOURCES = [
         generate: async (ctx) => {
             const templates = await getDynamicPersonaTemplates({ env: ctx.env });
             if (templates.length === 0) {
-                return "# Persona Templates\n\n> No templates available from API. Check configuration or use file-backed templates at `ema://templates/*`.\n";
+                return `# Persona Templates
+
+> API templates not available. Use one of these alternatives:
+
+## Option 1: Use the catalog tool directly
+\`\`\`
+catalog(method="list", type="templates")
+\`\`\`
+This connects to the API and may have different credentials.
+
+## Option 2: Use config fallbacks
+\`\`\`
+template(config="voice")   // Voice AI config template
+template(config="chat")    // Chat AI config template
+template(config="dashboard") // Dashboard AI config template
+\`\`\`
+
+## Option 3: Create from scratch
+\`\`\`
+persona(method="create", name="My AI", type="voice|chat|dashboard")
+\`\`\`
+`;
             }
             const byCategory = new Map();
             for (const t of templates) {
@@ -727,10 +727,11 @@ export class ResourceRegistry {
     buildResourceIndex() {
         const resources = this.list().filter((r) => r.uri !== "ema://index/all-resources");
         // Group resources by category
+        // Note: ema://templates/* file-backed resources removed - use API templates or generated fallbacks
         const docs = resources.filter((r) => r.uri.startsWith("ema://docs/"));
-        const templates = resources.filter((r) => r.uri.startsWith("ema://templates/"));
         const catalog = resources.filter((r) => r.uri.startsWith("ema://catalog/"));
         const rules = resources.filter((r) => r.uri.startsWith("ema://rules/"));
+        const schemas = resources.filter((r) => r.uri.startsWith("ema://schema/"));
         const markdown = `# Ema MCP Resources Index
 
 > Available resources exposed by the Ema MCP Server
@@ -742,9 +743,9 @@ export class ResourceRegistry {
 | Category | Count | Description |
 |----------|-------|-------------|
 | Documentation | ${docs.length} | User guides, README, tool references |
-| Templates | ${templates.length} | Persona configuration templates (voice/chat/dashboard) |
-| Catalog | ${catalog.length} | Agent catalog, workflow patterns, widgets |
+| Catalog | ${catalog.length} | Agent catalog, workflow patterns, templates |
 | Rules | ${rules.length} | Validation rules, anti-patterns, optimizations |
+| Schemas | ${schemas.length} | Action schemas, type definitions |
 
 ## Documentation (${docs.length})
 
@@ -752,14 +753,6 @@ export class ResourceRegistry {
 |-----|-------------|
 ${docs.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
 
-## Templates (${templates.length})
-
-> Use templates as starting points for new AI Employees
-
-| URI | Description |
-|-----|-------------|
-${templates.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
-
 ## Catalog (${catalog.length})
 
 > Dynamic catalogs generated from SDK knowledge
@@ -776,6 +769,14 @@ ${catalog.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
 |-----|-------------|
 ${rules.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
 
+## Schemas (${schemas.length})
+
+> Action schemas and type definitions
+
+| URI | Description |
+|-----|-------------|
+${schemas.map((r) => `| \`${r.uri}\` | ${r.description} |`).join("\n")}
+
 ## Usage
 
 To read a resource, use the \`resources/read\` endpoint:
@@ -795,7 +796,7 @@ To read a resource, use the \`resources/read\` endpoint:
 |------|-----|
 | Get agent definitions | Resource: \`ema://catalog/agents\` |
 | Get input/output compatibility rules | Resource: \`ema://rules/input-sources\` |
-| Get persona template | Resource: \`ema://templates/voice-ai/config\` |
+| Get persona templates | Resource: \`ema://catalog/persona-templates\` (API) or Tool: \`template(config="voice")\` |
 | Query live persona data | Tool: \`persona\` |
 | Generate a workflow | Tool: \`workflow\` |
 | Analyze an existing workflow | Tool: \`workflow(mode="analyze")\` |

package/dist/mcp/server.js

@@ -41,22 +41,22 @@ import { createVersionPolicyEngine } from "../sdk/version-policy.js";
 import { getToolkitRoot } from "../sdk/paths.js";
 import { SYNC_METADATA_KEY } from "../sdk/models.js";
 // Auto Builder Knowledge
-import { AGENT_CATALOG, WIDGET_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, VOICE_PERSONA_TEMPLATE, PROJECT_TYPES, getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
+import { AGENT_CATALOG, WIDGET_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, PROJECT_TYPES, getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
 // Workflow Analysis
 analyzeWorkflow, detectWorkflowIssues, validateWorkflowConnections, suggestWorkflowFixes, } from "../sdk/knowledge.js";
+// Template fallbacks (generated from protos, used when API unavailable)
+import { getTemplateFallback, getTemplateFieldDocs, VOICE_TEMPLATE_FALLBACK } from "../sdk/generated/template-fallbacks.js";
 // Workflow Compiler (Template-driven)
 import { compileWorkflow, } from "../sdk/workflow-generator.js";
 // V2 Tools (4 tools: persona, catalog, sync, env) - NEW DEFAULT
-import { generateToolsV2, } from "./tools-v2.js";
-// V1 Consolidated Tools (7 mode-based tools) - BACKWARDS COMPAT
-import { generateConsolidatedTools, } from "./tools-consolidated.js";
-// Legacy Tools (get_persona, find_personas, etc.) - DEPRECATED
-import { generateLegacyTools, } from "./tools-legacy.js";
-// Feature flags for tool versions
-// V2 is default (4 tools), set EMA_ENABLE_V1_TOOLS=true for 7-tool mode-based interface
-const ENABLE_V1_TOOLS = process.env.EMA_ENABLE_V1_TOOLS === "true";
-const ENABLE_LEGACY_TOOLS = process.env.EMA_ENABLE_LEGACY_TOOLS === "true";
-import { handleEnv, handlePersona, handleWorkflow, handleAction, handleData, handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
+import { generateTools, } from "./tools.js";
+import { handleEnv, handlePersona, 
+// handleWorkflow - removed, now using extracted handler from ./handlers/workflow/index.js
+handleAction, 
+// handleData - removed, now using extracted handler from ./handlers/data/index.js
+handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
+// Import extracted handlers
+import { handleWorkflow } from "./handlers/workflow/index.js";
 // Import from handler utilities (normalizeTriggerType uses generated enum labels)
 import { normalizeTriggerType } from "./handlers/utils.js";
 // Import from SDK proto-config (CANONICAL widget validation and merging)
@@ -1093,102 +1093,46 @@ function withEnvParam(props, required = []) {
 // Tool Definitions
 // ─────────────────────────────────────────────────────────────────────────────
 //
-// TOOL STRUCTURE:
-// 1. CONSOLIDATED TOOLS (9 tools) - Unix CLI pattern with flags
-//    - env, persona, workflow, action, template, knowledge, reference, sync, demo
-//    - Defined in: ./tools-consolidated.ts
-//
-// 2. LEGACY TOOLS (40+ tools) - Old separate tools for backwards compatibility  
-//    - Defined in: ./tools-legacy.ts
-//    - Enable with EMA_ENABLE_LEGACY_TOOLS=true
+// V2 TOOLS (5 tools) - LLM-optimized minimal interface
+//   - env, persona, catalog, workflow, sync
+//   - Defined in: ./tools.ts
 //
 // NAMING CONVENTION:
-// - Tool names are defined as BASE NAMES (e.g., "persona", "list_ai_employees")
+// - Tool names are defined as BASE NAMES (e.g., "persona")
 // - MCP clients prefix with "mcp_{server}_" (e.g., "mcp_ema_persona")
 //
 // ─────────────────────────────────────────────────────────────────────────────
 /**
- * Generate all available tools based on configuration
+ * Generate all available tools
  *
- * Tool versions:
- * - V2 (default): 4 tools (persona, catalog, sync, env) - LLM-optimized
- * - V1: 7 mode-based tools - set EMA_ENABLE_V1_TOOLS=true
- * - Legacy: Individual tools - set EMA_ENABLE_LEGACY_TOOLS=true
+ * V2: 5 tools (persona, catalog, workflow, sync, env) - LLM-optimized
  *
- * Why V2 by default:
+ * Why V2:
  * - Minimal tool count optimizes LLM tool selection
  * - Data operations under persona (always persona-scoped)
  * - Catalog consolidates all reference data (actions, templates, etc.)
- * - Clear separation: entity (persona), reference (catalog), operation (sync)
+ * - Clear separation: entity (persona), reference (catalog), operation (sync, workflow)
  */
 function generateAllTools() {
     const envNames = getAvailableEnvironments().map(e => e.name);
     const defaultEnv = getDefaultEnvName();
-    // V1 mode-based tools (for backwards compat)
-    if (ENABLE_V1_TOOLS) {
-        console.error("[MCP] V1 mode-based tools enabled via EMA_ENABLE_V1_TOOLS=true");
-        const consolidatedTools = generateConsolidatedTools(envNames, defaultEnv);
-        if (ENABLE_LEGACY_TOOLS) {
-            console.error("[MCP] WARNING: Legacy tools also enabled");
-            const legacyTools = generateLegacyTools(envNames, defaultEnv);
-            return [...consolidatedTools, ...legacyTools];
-        }
-        return consolidatedTools;
-    }
-    // V2 minimal tools (default) - 4 tools: persona, catalog, sync, env
-    const v2Tools = generateToolsV2(envNames, defaultEnv);
-    if (ENABLE_LEGACY_TOOLS) {
-        console.error("[MCP] WARNING: Legacy tools enabled alongside V2");
-        const legacyTools = generateLegacyTools(envNames, defaultEnv);
-        return [...v2Tools, ...legacyTools];
-    }
-    return v2Tools;
+    return generateTools(envNames, defaultEnv);
 }
 // Generate tools (called once at module load)
 const TOOLS = generateAllTools();
 // ─────────────────────────────────────────────────────────────────────────────
-// ADDITIONAL TOOLS (not in consolidated or legacy)
-// These are special-purpose tools that don't fit the standard patterns
+// ADDITIONAL TOOLS (special-purpose inline tools)
+// These handle specific operations that don't fit the V2 pattern
 // ─────────────────────────────────────────────────────────────────────────────
 const ADDITIONAL_TOOLS = [
-    // ─────────────────────────────────────────────────────────────────────────
-    // NOTE: Legacy tools (get_persona, find_personas, create_ai_employee, etc.)
-    // have been moved to ./tools-legacy.ts for backwards compatibility.
-    //
-    // Consolidated tools (persona, workflow, action, etc.) are generated from
-    // ./tools-consolidated.ts following Unix CLI patterns.
+    // NOTE: Tools (persona, catalog, workflow, sync, env) are in ./tools.ts
     //
-    // Only special-purpose tools remain here:
-    // - "workflow" (unified tool) - experimental, bridges old and new patterns
-    // - Demo data tools - special-purpose data generation
-    // ─────────────────────────────────────────────────────────────────────────
-    // INLINE LEGACY TOOLS REMOVED
-    // All legacy tools (get_workflow_action, find_workflow_actions, compare_ai_employees,
-    // list_ai_employee_templates, sync, sync_info, list_auto_builder_agents, etc.)
-    // have been moved to ./tools-legacy.ts
-    // ─────────────────────────────────────────────────────────────────────────
-    // ─────────────────────────────────────────────────────────────────────────────
-    // LEGACY INLINE TOOLS REMOVED - See ./tools-legacy.ts
-    // ─────────────────────────────────────────────────────────────────────────────
-    // The following tools have been removed from this file and are now generated
-    // from tools-legacy.ts: list_auto_builder_agents, get_auto_builder_agent,
-    // suggest_agents_for_use_case, get_workflow_pattern, list_workflow_patterns,
-    // check_type_compatibility, get_widget_reference, get_qualifying_questions,
-    // get_voice_persona_template, validate_workflow_prompt, get_auto_builder_guidance,
-    // get_platform_concept, list_platform_concepts, get_common_mistakes,
-    // get_debug_checklist, get_workflow_execution_model, analyze_workflow,
-    // detect_workflow_issues, validate_workflow_connections, suggest_workflow_fixes,
-    // compare_workflow_versions, get_workflow_metrics, compile_workflow,
-    // upload_data_source, delete_data_source, list_data_sources, get_embedding_status,
+    // Special-purpose tools here:
+    // - compile_workflow - Direct workflow compilation
+    // - Demo data tools - RAG document generation/validation
+    // - Data source tools - Upload/delete/manage knowledge sources
     // toggle_embedding
     // ─────────────────────────────────────────────────────────────────────────────
-    // The remaining legacy tools are handled by the LEGACY_TOOL_MAPPING in
-    // tools-consolidated.ts for routing to consolidated handlers.
-    //
-    // INLINE DEFINITIONS REMOVED - They are now in tools-legacy.ts
-    // (analyze_workflow, detect_workflow_issues, validate_workflow_connections, suggest_workflow_fixes)
-    // (compare_workflow_versions, get_workflow_metrics) - moved to tools-legacy.ts
-    // ─────────────────────────────────────────────────────────────────────────────
     // Workflow Compilation - Template-driven, no biased patterns
     // Read ema://catalog/patterns for pattern references, then construct nodes
     // ─────────────────────────────────────────────────────────────────────────────
@@ -1606,11 +1550,6 @@ Returns:
             required: ["entity_type"],
         },
     },
-    // ═══════════════════════════════════════════════════════════════════════════
-    // CONSOLIDATED TOOLS (Unix CLI pattern)
-    // These 9 tools follow Unix conventions: single command with flags
-    // ═══════════════════════════════════════════════════════════════════════════
-    ...generateConsolidatedTools(getAvailableEnvironments().map(e => e.name), getDefaultEnvName()),
 ];
 const toolHandlers = {
     // Environment Management
@@ -2826,10 +2765,14 @@ const toolHandlers = {
         };
     },
     get_voice_persona_template: async () => {
+        // Use generated fallback from proto definitions
+        // In production, prefer API templates via client.getPersonaTemplates()
+        const template = getTemplateFallback("voice");
         return {
-            template: VOICE_PERSONA_TEMPLATE,
-            required_fields: ["welcomeMessage", "identityAndPurpose", "takeActionInstructions", "hangupInstructions"],
-            optional_fields: ["transferCallInstructions", "speechCharacteristics", "systemPrompt", "formFillingInstructions", "waitMessage"],
+            template: template || VOICE_TEMPLATE_FALLBACK,
+            field_docs: getTemplateFieldDocs("voice"),
+            required_fields: ["conversationSettings.welcomeMessage", "conversationSettings.identityAndPurpose", "conversationSettings.takeActionInstructions", "conversationSettings.hangupInstructions"],
+            optional_fields: ["conversationSettings.transferCallInstructions", "conversationSettings.speechCharacteristics", "conversationSettings.systemPrompt", "conversationSettings.formFillingInstructions", "conversationSettings.waitMessage"],
             project_type: PROJECT_TYPES.voice,
             widget_ids: {
                 voiceSettings: 38,
@@ -2837,12 +2780,8 @@ const toolHandlers = {
                 vadSettings: 43,
                 dataStorageSettings: 42,
             },
-            instructions: [
-                "Replace all {placeholder} values with actual content",
-                "takeActionInstructions uses </Case N> format for each action",
-                "speechCharacteristics should include TTS pronunciation rules",
-                "systemPrompt defines tool calling behavior",
-            ],
+            _source: "generated_fallback",
+            _note: "This template is auto-generated from proto definitions. For live templates, use client.getPersonaTemplates().",
         };
     },
     validate_workflow_prompt: async (args) => {
@@ -4049,28 +3988,32 @@ const toolHandlers = {
                 const { handleData: handleDataNew } = await import("./handlers/data/index.js");
                 return handleDataNew({ persona_id: personaId, env: args.env, data }, client);
             }
-            // LEGACY FLAG FORMAT (backwards compatibility)
+            // LEGACY FLAG FORMAT (backwards compatibility) - use extracted handler
+            const { handleData: handleDataExtracted } = await import("./handlers/data/index.js");
+            const readFileFn = (path) => fs.readFile(path);
             if (data.list === true) {
-                return handleData({ mode: "list", persona_id: personaId, env: args.env }, client, (path) => fs.readFile(path));
+                return handleDataExtracted({ method: "list", persona_id: personaId, env: args.env }, client, readFileFn);
             }
             if (typeof data.upload === "string") {
-                return handleData({ mode: "upload", persona_id: personaId, file: data.upload, env: args.env }, client, (path) => fs.readFile(path));
+                return handleDataExtracted({ method: "upload", persona_id: personaId, data: { path: data.upload }, env: args.env }, client, readFileFn);
             }
             if (typeof data.delete === "string") {
-                return handleData({ mode: "delete", persona_id: personaId, file_id: data.delete, env: args.env }, client, (path) => fs.readFile(path));
+                return handleDataExtracted({ method: "delete", persona_id: personaId, data: { file_id: data.delete }, env: args.env }, client, readFileFn);
             }
             if (typeof data.generate === "string" || data.template) {
-                return handleData({
-                    mode: "generate",
+                return handleDataExtracted({
+                    method: "generate",
                     persona_id: personaId,
-                    input: data.generate,
-                    from: data.template,
-                    count: data.count,
+                    data: {
+                        input: data.generate,
+                        from: data.template,
+                        count: data.count,
+                    },
                     env: args.env
-                }, client, (path) => fs.readFile(path));
+                }, client, readFileFn);
             }
             if (typeof data.embed === "boolean") {
-                return handleData({ mode: "embedding", persona_id: personaId, enabled: data.embed, env: args.env }, client, (path) => fs.readFile(path));
+                return handleDataExtracted({ method: "embedding", persona_id: personaId, data: { enabled: data.embed }, env: args.env }, client, readFileFn);
             }
             if (typeof data.search === "string") {
                 return handleKnowledge({ mode: "search", persona_id: personaId, query: data.search, env: args.env }, client, (path) => fs.readFile(path));
@@ -4149,7 +4092,9 @@ const toolHandlers = {
     data: async (args) => {
         const client = createClient(args.env);
         const fs = await import("fs/promises");
-        return handleData(args, client, (path) => fs.readFile(path));
+        // Use extracted handler
+        const { handleData: handleDataExtracted } = await import("./handlers/data/index.js");
+        return handleDataExtracted(args, client, (path) => fs.readFile(path));
     },
     reference: async (args) => {
         // v2: expanded reference handler with envs, actions, templates, patterns support
@@ -4169,9 +4114,11 @@ const toolHandlers = {
     // catalog: Consolidated reference data (actions, templates, widgets, voices, patterns, concepts)
     catalog: async (args) => {
         const catalogType = args.type;
+        const method = args.method;
         const id = args.id;
         const query = args.query;
-        const recommend = args.recommend;
+        // Note: schema uses 'for' parameter for recommend (not 'recommend')
+        const forUseCase = args.for;
         const category = args.category;
         const client = createClient(args.env);
         if (!catalogType) {
@@ -4183,9 +4130,16 @@ const toolHandlers = {
         switch (catalogType) {
             case "actions": {
                 // Route to action handler
-                if (recommend) {
-                    const suggestions = suggestAgentsForUseCase(recommend);
-                    return { type: "actions", use_case: recommend, recommendations: suggestions };
+                if (method === "recommend" && forUseCase) {
+                    const suggestions = suggestAgentsForUseCase(forUseCase);
+                    return {
+                        type: "actions",
+                        use_case: forUseCase,
+                        recommendations: suggestions,
+                        _tip: suggestions.length > 0
+                            ? `Found ${suggestions.length} relevant agents. Use catalog(method="get", type="actions", id="<name>") for details.`
+                            : "No specific recommendations. Try browsing with catalog(method=\"list\", type=\"actions\").",
+                    };
                 }
                 if (id) {
                     const action = getAgentByName(id);
@@ -4209,7 +4163,9 @@ const toolHandlers = {
                 return {
                     type: "actions",
                     count: actions.length,
-                    actions: actions.map(a => ({ name: a.actionName, displayName: a.displayName, category: a.category, description: a.description }))
+                    actions: actions.map(a => ({ name: a.actionName, displayName: a.displayName, category: a.category, description: a.description })),
+                    _tip: "Get details: catalog(method=\"get\", type=\"actions\", id=\"<name>\")",
+                    _next_step: actions.length > 0 ? `catalog(method="get", type="actions", id="${actions[0].actionName}")` : undefined,
                 };
             }
             case "templates": {
@@ -4231,7 +4187,13 @@ const toolHandlers = {
                 return {
                     type: "templates",
                     count: filtered.length,
-                    templates: filtered.map(t => ({ id: t.id, name: t.name, description: t.description }))
+                    templates: filtered.map(t => ({ id: t.id, name: t.name, description: t.description })),
+                    _tip: filtered.length > 0
+                        ? "Create from template: persona(method=\"create\", name=\"My AI\", from=\"<template_id>\")"
+                        : "No templates found. Create from scratch: persona(method=\"create\", name=\"My AI\", type=\"voice|chat|dashboard\")",
+                    _next_step: filtered.length > 0
+                        ? `catalog(method="get", type="templates", id="${filtered[0].id}")`
+                        : undefined,
                 };
             }
             case "widgets": {
@@ -4266,13 +4228,20 @@ const toolHandlers = {
                 };
             }
             case "patterns": {
-                if (recommend) {
+                if (method === "recommend" && forUseCase) {
                     // Find patterns matching use case
-                    const q = recommend.toLowerCase();
+                    const q = forUseCase.toLowerCase();
                     const matches = WORKFLOW_PATTERNS.filter(p => p.name.toLowerCase().includes(q) ||
                         p.description.toLowerCase().includes(q) ||
                         p.useCase.toLowerCase().includes(q));
-                    return { type: "patterns", use_case: recommend, recommendations: matches };
+                    return {
+                        type: "patterns",
+                        use_case: forUseCase,
+                        recommendations: matches,
+                        _tip: matches.length > 0
+                            ? `Found ${matches.length} matching patterns. Use catalog(method="get", type="patterns", id="<name>") for full details.`
+                            : "No matching patterns. Try catalog(method=\"list\", type=\"patterns\") to see all available.",
+                    };
                 }
                 if (id) {
                     const pattern = WORKFLOW_PATTERNS.find(p => p.name === id);
@@ -4324,14 +4293,14 @@ const toolHandlers = {
     // Note: demo is handled via a consolidated adapter below
 };
 // ─────────────────────────────────────────────────────────────────────────────
-// Consolidated Tool Adapters (contract ↔ implementation)
+// V2 Tool Adapters (contract ↔ implementation)
 // ─────────────────────────────────────────────────────────────────────────────
 //
-// The tool schemas in tools-consolidated.ts are the public MCP contract.
-// This file still contains a number of proven "legacy" handlers that we reuse
+// The tool schemas in tools.ts are the public MCP contract.
+// This file still contains proven handlers that we reuse
 // (e.g. deploy_workflow, optimize_workflow, compile_workflow, etc.).
 //
-// These adapters ensure the consolidated tool surface behaves as documented,
+// These adapters ensure the V2 tool surface behaves as documented,
 // while preserving the existing internal implementations.
 const legacyWorkflowTool = toolHandlers.workflow;
 const legacyDeployWorkflow = toolHandlers.deploy_workflow;
@@ -4904,8 +4873,8 @@ function determineOperation(toolName, args) {
     if (toolName === "catalog") {
         if (args.id)
             return "get";
-        if (args.recommend)
-            return "recommend";
+        if (args.for)
+            return "recommend"; // V2 schema uses 'for' parameter
         if (args.query)
             return "search";
         return "list";

package/dist/mcp/{tools-v2.js → tools.js}

@@ -19,7 +19,7 @@ import { generateInputDescription, SUPPORTED_OPERATIONS, LIMITATIONS } from "./w
 /**
  * Generate the v2 tool set
  */
-export function generateToolsV2(envNames, defaultEnv) {
+export function generateTools(envNames, defaultEnv) {
     const envDescription = envNames.length > 0
         ? `Environment: ${envNames.join(", ")}. Default: ${defaultEnv}`
         : "Environment name";