@ema.co/mcp-toolkit 1.5.1 → 1.6.0

package/docs/mcp-tools-guide.md

@@ -4,64 +4,109 @@ This MCP server is intentionally designed for **LLM + agent ergonomics**:
 
 - **Few tools, consistent shapes**: a small set of noun-based tools with predictable `mode` / flag patterns
 - **Resources-first**: use `ema://...` resources for reference data/templates, then tools for actions
-- **Low ambiguity**: defaults are chosen to avoid “which of 5 similar tools?” confusion
+- **Low ambiguity**: defaults are chosen to avoid "which of 5 similar tools?" confusion
 
 ## Tool names in MCP clients
 
-The server defines **base tool names** like `persona`, `workflow`, `template`.
+The server defines **base tool names** like `persona`, `template`.
 
-Some clients show a **prefixed name** (for example Cursor: `mcp_ema_workflow`). Always call **the tool name your client displays**; the semantics are the same.
+Some clients show a **prefixed name** (for example Cursor: `mcp_ema_persona`). Always call **the tool name your client displays**; the semantics are the same.
 
-## The tool set (9 tools)
+## The tool set (8 tools)
 
 | Tool | Purpose |
 |------|---------|
 | `env` | List available environments and which is default |
-| `persona` | AI Employee management (get/list/create/update/compare/templates) |
-| `workflow` | Generate/analyze/deploy/optimize/compare/compile workflows |
+| `persona` | **UNIFIED**: Create/modify/analyze/optimize/list AI Employees |
 | `action` | Actions/agents lookup (API + embedded docs), plus recommendations |
-| `template` | Workflow patterns, widget references, qualifying questions |
+| `template` | Qualifying questions, workflow patterns, widget references |
 | `knowledge` | Data sources + embedding (upload/list/delete/status/toggle) |
 | `reference` | Concepts + guidance + validation + common mistakes |
 | `sync` | Sync across environments (run/status/config) |
 | `demo` | Demo/RAG document utilities (template/consolidate/generate/validate) |
 
+> **Note**: The `workflow` tool is **DEPRECATED**. Use `persona` instead - it handles everything.
+
+## ⚠️ THE KEY INSIGHT: ONE CALL
+
+Creating an AI Employee should be **ONE `persona()` call**, not multiple calls.
+
+```typescript
+persona(
+  input="Voice AI SDR: qualifies leads, identifies use-case, sends follow-up email",
+  type="voice",
+  name="Sales SDR",
+  preview=false
+)
+```
+
+**MCP handles internally:** template selection, config generation, widget formatting, API orchestration.
+
 ## Start-here flows (LLM-friendly)
 
 ### Create a new AI Employee (greenfield)
 
-1. **Requirements**: `template(questions=true)` (and `template(questions=true, category="Voice")` for voice)
-2. **Pick agents/pattern**: `action(suggest="<use case>")`
-3. **Get the pattern**: `template(pattern="<pattern>")`
-4. **Generate workflow** (preview by default):
+1. **Get qualifying questions from MCP**: `template(questions=true)`
+2. **Ask user those questions**
+3. **Create in ONE call**:
    ```typescript
-   workflow(input="<requirements>", type="chat|voice|dashboard")
+   persona(
+     input="<everything from user answers>",
+     name="My AI Employee",
+     type="voice",
+     preview=false
+   )
    ```
-5. **Create persona** (if needed): `persona(mode="create", name="...", type="chat|voice|dashboard")`
-6. **Deploy** (preview=false):
-   ```typescript
-   workflow(input="<requirements>", persona_id="<id>", preview=false)
-   ```
-7. **Review**: `workflow(mode="analyze", persona_id="...")`
 
-### Extend an existing AI Employee (brownfield)
+### Complex Workflows (email, HITL, multi-intent)
 
-**Combine multiple changes in one command!**
+For complex workflows, MCP returns `status: "needs_llm_generation"` with a prompt you send to an LLM:
 
 ```typescript
-// Preview changes (safe default)
-workflow(mode="extend", persona_id="abc-123", input="add caller_type categorizer, add HITL before email")
+// Step 1: Request creation
+result = persona(
+  input="SDR that qualifies leads and sends follow-up emails",
+  type="voice",
+  name="Sales SDR",
+  preview=true
+)
+
+// If result.status === "needs_llm_generation":
+// Step 2: Send result.llm_prompt to an LLM (Claude, GPT-4, etc.)
+// Step 3: Deploy the LLM's workflow response
+persona(
+  workflow_def=llm_response_json,
+  name="Sales SDR",
+  type="voice",
+  preview=false
+)
+```
 
-// Deploy changes
-workflow(mode="extend", persona_id="abc-123", input="...", preview=false)
+**Simple workflows** (basic Q&A, search + respond) deploy directly without this extra step.
+
+### Modify an existing AI Employee (brownfield)
+
+```typescript
+// Optional: Understand what exists first
+persona(id="abc-123")
+
+// Modify in ONE call
+persona(id="abc-123", input="add HITL before email, add compliance intent", preview=false)
 ```
 
-### Review or debug an existing AI Employee
+### Analyze/Review an AI Employee
 
-1. Fetch full workflow: `persona(id="<id-or-exact-name>", include_workflow=true)`
-2. Analyze: `workflow(mode="analyze", persona_id="<persona_id>")`
-3. Preview fixes: `workflow(mode="optimize", persona_id="<persona_id>")`
-4. Apply fixes: `workflow(mode="optimize", persona_id="<persona_id>", preview=false)`
+```typescript
+persona(id="abc-123")                         // Get with analysis
+persona(id="abc-123", include_workflow=true)  // Include full workflow
+```
+
+### Optimize (auto-fix issues)
+
+```typescript
+persona(id="abc-123", optimize=true)                  // Preview fixes
+persona(id="abc-123", optimize=true, preview=false)   // Apply fixes
+```
 
 ### Upload / manage knowledge base documents
 
@@ -74,116 +119,96 @@ workflow(mode="extend", persona_id="abc-123", input="...", preview=false)
 - Run (single): `sync(id="My Bot", source="demo", target="dev", dry_run=true|false)`
 - Run (all tagged): `sync(target="dev", scope="all", dry_run=true|false)`
 - Status: `sync(mode="status", id="My Bot", env="dev")`
-- List all synced in env: `sync(mode="status", list_synced=true, env="dev")`
-- Config: `sync(mode="config")`
 
 ### Version / snapshot AI Employees
 
-Take snapshots before making changes, restore if something breaks.
-
 ```typescript
 // Before a risky change - create a snapshot
 persona(id="My Bot", mode="version_create", message="Before adding HITL")
 
 // Make changes...
-workflow(mode="extend", persona_id="abc", input="add HITL before email", preview=false)
+persona(id="abc", input="add HITL before email", preview=false)
 
-// If something breaks - list versions and restore
+// If something breaks - restore
 persona(id="My Bot", mode="version_list")
 persona(id="My Bot", mode="version_restore", version="v3")
 ```
 
-**Auto-snapshot on deploy:**
+## Tool reference (high-signal)
+
+### `persona` (UNIFIED - use for everything)
+
+**Create new AI Employee:**
 ```typescript
-persona(id="My Bot", mode="version_policy", auto_on_deploy=true)
-// Now every deploy automatically creates a snapshot first
+persona(input="<what it does>", type="voice", name="My Bot", preview=false)
 ```
 
-### Demo data → RAG-ready Markdown → upload
+**Modify existing:**
+```typescript
+persona(id="abc", input="add HITL before email", preview=false)
+```
 
-1. Get a template: `demo(mode="template", entity="customer")`
-2. Consolidate a dataset: `demo(mode="consolidate", source="./data", output="./kb", entity="customer", primary="customers.json", joins=[...])`
-3. Upload: `knowledge(persona_id="...", mode="upload", file="/full/path/to/kb/customer_*.md")`
+**Analyze/Get:**
+```typescript
+persona(id="abc")
+persona(id="abc", include_workflow=true)
+```
 
-## Tool reference (high-signal)
+**Optimize:**
+```typescript
+persona(id="abc", optimize=true, preview=false)
+```
 
-### `persona`
-
-- **Get**: `persona(id="...", include_workflow=true)`
-- **List/search**: `persona(all=true)` / `persona(query="support", status="active")`
-- **Create**: `persona(mode="create", name="...", type="chat|voice|dashboard")`
-- **Update**: `persona(id="<id>", mode="update", name="...", description="...", enabled=true|false)`
-- **Compare**: `persona(id="<id>", mode="compare", compare_to="<id>", compare_env="dev")`
-- **Templates**: `persona(templates=true)`
-- **Version management**:
-  ```typescript
-  persona(id="abc", mode="version_create", message="Before major update")  // Create snapshot
-  persona(id="abc", mode="version_list")                                   // List all versions
-  persona(id="abc", mode="version_get", version="v3")                      // Get specific version
-  persona(id="abc", mode="version_compare", v1="v2", v2="v3")              // Compare versions
-  persona(id="abc", mode="version_restore", version="v2")                  // Restore to version
-  persona(id="abc", mode="version_policy", auto_on_deploy=true)            // Auto-snapshot settings
-  ```
-
-### `workflow`
-
-All modification modes default to `preview=true` for safety. Use `preview=false` to deploy.
-
-- **Generate (greenfield)**: Create new workflow
-  ```typescript
-  workflow(input="IT helpdesk with KB search")                    // Preview
-  workflow(input="...", persona_id="abc", preview=false)          // Generate AND deploy
-  ```
-
-- **Extend (brownfield)**: Modify existing workflow with natural language
-  ```typescript
-  workflow(mode="extend", persona_id="abc", input="add caller_type categorizer")
-  workflow(mode="extend", persona_id="abc", input="add X, add Y, add Z")  // Multiple changes!
-  workflow(mode="extend", persona_id="abc", input="...", preview=false)   // Extend AND deploy
-  ```
-
-- **Optimize**: Fix issues in existing workflow
-  ```typescript
-  workflow(mode="optimize", persona_id="abc")                     // Preview fixes
-  workflow(mode="optimize", persona_id="abc", preview=false)      // Apply fixes
-  ```
-
-- **Analyze** (always read-only):
-  ```typescript
-  workflow(mode="analyze", persona_id="abc")
-  workflow(mode="analyze", workflow_def={...})
-  workflow(mode="analyze", persona_id="abc", include=["issues", "fixes"])
-  ```
-
-- **Compare** (always read-only):
-  ```typescript
-  workflow(mode="compare", persona_id="abc", compare_to="def")
-  ```
-
-- **Compile** (returns workflow_def from explicit node spec):
-  ```typescript
-  workflow(mode="compile", name="...", description="...", nodes=[...])
-  ```
+**List/Search:**
+```typescript
+persona(all=true)
+persona(query="support", status="active")
+```
 
-### `action`
+**Compare:**
+```typescript
+persona(id="abc", compare_to="def")
+```
 
-- **Get**: `action(id="chat_categorizer", include_docs=true)`
-- **List/search**: `action(all=true)` / `action(query="search")` / `action(category="routing")`
-- **Suggest**: `action(suggest="IT helpdesk that creates ServiceNow tickets")`
+**Version management:**
+```typescript
+persona(id="abc", mode="version_create", message="Before update")
+persona(id="abc", mode="version_list")
+persona(id="abc", mode="version_restore", version="v2")
+persona(id="abc", mode="version_policy", auto_on_deploy=true)
+```
 
 ### `template`
 
-- **Patterns**: `template(patterns=true)` / `template(pattern="intent-routing")`
-- **Qualifying questions**: `template(questions=true)` / `template(questions=true, category="Voice", required_only=true)`
-- **Widget reference**: `template(widgets="voice")`
+**Primary use - Get qualifying questions:**
+```typescript
+template(questions=true)                    // All questions
+template(questions=true, category="Voice")  // Voice-specific
+```
+
+**Reference (understand options):**
+```typescript
+template(patterns=true)
+template(pattern="intent-routing")
+template(widgets="voice")
+```
+
+### `action`
+
+```typescript
+action(id="chat_categorizer", include_docs=true)   // Get specific
+action(all=true)                                    // List all
+action(suggest="IT helpdesk with ServiceNow")      // Get recommendations
+```
 
 ### `reference`
 
-- **Concept**: `reference(concept="HITL")`
-- **Guidance**: `reference(guidance="categorizer-routing")`
-- **Validate Auto Builder prompt**: `reference(validate_prompt="<prompt>")`
-- **Common mistakes**: `reference(mistakes=true)`
-- **Debug checklist**: `reference(checklist=true)`
+```typescript
+reference(concept="HITL")
+reference(guidance="categorizer-routing")
+reference(mistakes=true)
+reference(checklist=true)
+```
 
 ## Resources (read-first)
 
@@ -191,89 +216,39 @@ Start with:
 
 - `ema://index/all-resources` (index)
 - `ema://docs/readme` (toolkit overview)
-- `ema://docs/ema-user-guide` (platform concepts)
 - `ema://catalog/agents-summary` (quick agent overview)
-- `ema://catalog/templates` (persona templates from API - dynamic)
-- `ema://catalog/templates-summary` (template overview - dynamic)
-- `ema://catalog/patterns` (workflow patterns)
-- `ema://rules/input-sources` and `ema://rules/anti-patterns` (validation rules)
+- `ema://catalog/templates` (persona templates - dynamic)
+- `ema://rules/anti-patterns` (what NOT to do)
 
 ## Auto-Fix Capabilities
 
-The `workflow(mode="optimize")` can automatically fix common issues:
+The `persona(id="...", optimize=true)` can automatically fix common issues:
 
 | Issue | Severity | Auto-Fix? | Action |
 |-------|----------|-----------|--------|
 | `orphan` | warning | ✅ | Removes unreachable nodes |
 | `dead_end` | critical | ✅ | Adds results mapping |
-| `missing_workflow_output` | critical | ✅ | Adds results mapping for response nodes |
-| `wrong_input_source` (email_to) | warning | ✅ | Adds `entity_extraction` node, wires to extracted `email_address` |
-| `wrong_input_source` (query) | warning | ✅ | Rewires from `chat_conversation` to `user_query` |
-| `missing_fallback` | critical | ✅ | Adds Fallback category to categorizer |
-| `type_mismatch` | critical | ✅ | Rewires to type-compatible source |
+| `missing_workflow_output` | critical | ✅ | Adds results mapping |
+| `wrong_input_source` (email_to) | warning | ✅ | Adds entity_extraction |
+| `missing_fallback` | critical | ✅ | Adds Fallback category |
+| `type_mismatch` | critical | ✅ | Rewires to compatible source |
 | `cycle` | critical | ❌ | Requires manual restructuring |
-| `incomplete_hitl` | critical | ❌ | Needs success/failure response node configuration |
-| `side_effect_without_hitl` | info | ℹ️ | Informational only - HITL is opt-in |
 
 ## HITL (Human-in-the-Loop) Policy
 
-**HITL is opt-in, not forced by default.** The MCP does NOT automatically add HITL for email or external actions.
-
-| Scenario | Default Behavior | How to Add HITL |
-|----------|-----------------|-----------------|
-| Send email | ❌ No HITL | Request explicitly: "add approval before sending" |
-| External API call | ❌ No HITL | Request explicitly: "require human approval" |
-| Create/update records | ❌ No HITL | Request explicitly in prompt |
-
-To add HITL after deployment: `workflow(persona_id="...", input="add human approval before email")`
-
-
-## Brownfield Workflow Extension
-
-Extend existing workflows with new capabilities while preserving existing logic.
-
-### Usage
-
-```typescript
-// Add new nodes/intents
-workflow(persona_id="abc", input="add caller_type categorizer with Advisor and Client roles")
-
-// Add enum options to existing categorizer
-workflow(persona_id="abc", input="add Market Analysis intent to the categorizer")
-
-// Add custom wiring  
-workflow(persona_id="abc", input="add send_email node connected to entity_extractor output")
-
-// Merge a complete workflow_def (extend mode - preserves existing)
-workflow(persona_id="abc", workflow_def={...}, merge_mode="extend")
-
-// Replace with a new workflow (destructive)
-workflow(persona_id="abc", workflow_def={...}, merge_mode="replace", force=true)
-```
-
-### Merge Modes
-
-| Mode | Behavior |
-|------|----------|
-| `extend` (default) | Add new nodes, preserve existing, merge enums |
-| `replace` | Replace nodes not in incoming (destructive) |
-
-### Capabilities
-
-| Capability | Example |
-|------------|---------|
-| ✅ Add new nodes | `input="add password reset intent"` |
-| ✅ Add enum options | `input="add Advisor/Client to caller_type"` |
-| ✅ Add HITL gates | `input="add approval before sending emails"` |
-| ✅ Modify node wiring | `input="wire entity_extraction to email handler"` |
-| ✅ Preserve existing logic | Existing nodes/enums kept unless modified |
+**HITL is opt-in, not forced by default.**
 
+| Scenario | Default | How to Add HITL |
+|----------|---------|-----------------|
+| Send email | ❌ No HITL | `persona(id="...", input="add approval before sending")` |
+| External API | ❌ No HITL | Request explicitly in input |
+| Create records | ❌ No HITL | Request explicitly in input |
 
 ## Auto Builder Prompt Length Limits
 
-**⚠️ CRITICAL:** Auto Builder has strict prompt length limits. Long prompts (>2500 chars) cause timeouts.
+**⚠️ CRITICAL:** Auto Builder has strict prompt length limits (~2500 chars).
 
-### Good Prompt Format (Works)
+### Good Prompt Format
 ```text
 Voice AI for [use case]. Supports [capabilities].
 
@@ -285,33 +260,24 @@ Core Capabilities:
 Rules:
 • Rule 1
 • Rule 2
-
-Output: All responses return through WORKFLOW_OUTPUT.
 ```
 
 ### Bad Prompt Format (Times Out)
 - Narrative descriptions with multiple paragraphs
 - Example conversations embedded in prompt
-- Detailed step-by-step flows for each intent
 - Prompts > 2500 characters
 
-The MCP automatically condenses long prompts via `condensePromptForAutobuilder()`, but best practice is to provide concise prompts from the start.
-
-## Workflow Generation Strategy
-
-| Approach | When to Use | Notes |
-|----------|-------------|-------|
-| **Local compilation** | Simple/medium workflows | `workflow(mode="compile", ...)` - reliable, fast |
-| **Auto Builder** | Complex/exploratory workflows | Requires concise prompts (<2500 chars) |
-
-Prefer local compilation for deterministic results. Use `use_autobuilder=false` flag when generating workflows.
+## Deprecated: `workflow` tool
 
-## Legacy tools (migration only)
+The `workflow` tool is **DEPRECATED**. It still works but routes to `persona`.
 
-Legacy tools are **disabled by default** to reduce duplicate semantics and tool confusion for LLMs.
-
-If you must enable them (temporary):
-
-- Set `EMA_ENABLE_LEGACY_TOOLS=true`
-- Prefer the consolidated tools for new usage
+**Migration:**
+```typescript
+// OLD (deprecated)
+workflow(input="...", type="voice", name="Bot", preview=false)
+workflow(persona_id="abc", input="add HITL")
 
+// NEW (use this)
+persona(input="...", type="voice", name="Bot", preview=false)
+persona(id="abc", input="add HITL")
+```