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

package/docs/blog/mcp-tool-design-lessons.md

@@ -1,309 +0,0 @@
-# Designing MCP Tools for How People Actually Use Them
-
-*Lessons from restructuring an MCP server from 7 "super tools" to 20 focused operations*
-
----
-
-## The Starting Point
-
-We had built an MCP (Model Context Protocol) server for managing AI Employees on the Ema platform. It worked. Users could create personas, manage workflows, sync across environments. But something felt off.
-
-Our server had consolidated ~45 original tools into just 7 "super tools" using a `mode` parameter:
-
-```typescript
-// What we had
-persona(mode="list")
-persona(mode="get", id="abc-123")
-persona(mode="create", name="Sales Bot", type="voice", input="...")
-persona(mode="analyze", id="abc-123", fix=true, include=["workflow", "config"])
-```
-
-Fewer tools seemed better, right? Unix philosophy: do one thing well. Except each tool had 30+ parameters, and the LLM had to figure out which parameters applied to which mode.
-
-It was clever engineering. It was also wrong.
-
----
-
-## The Problems We Discovered
-
-### Problem 1: Parameter Sprawl
-
-Every time an LLM called our `persona` tool, it saw this schema:
-
-```json
-{
-  "properties": {
-    "mode": { "enum": ["list", "get", "create", "update", "clone", "analyze", "sanitize", "templates", ...] },
-    "id": { "description": "Persona ID" },
-    "name": { "description": "Name for new persona" },
-    "type": { "enum": ["voice", "chat", "dashboard"] },
-    "from": { "description": "Template or persona to clone from" },
-    "input": { "description": "Natural language description" },
-    "include_data": { "description": "Include data when cloning" },
-    "sanitize": { "description": "Remove PII" },
-    "fix": { "description": "Auto-fix issues" },
-    "include": { "description": "What to include in analysis" },
-    "proto_config": { "description": "Override config" },
-    "workflow": { "description": "Direct workflow JSON" },
-    // ... 20 more parameters
-  }
-}
-```
-
-The LLM saw 30 parameters when it only needed 2 for a simple "get me this persona" request. Confusion ensued.
-
-### Problem 2: Inconsistent Patterns
-
-We had three different patterns across our 7 tools:
-
-| Tool | Pattern |
-|------|---------|
-| `persona` | `mode` parameter required |
-| `action` | Flag-based (`all=true`, `suggest="..."`) |
-| `reference` | Hybrid (`type` enum + individual flags) |
-
-Which pattern should the LLM use? It depended on which tool. This meant the LLM had to learn 3 different interaction styles.
-
-### Problem 3: We Designed for the Wrong User
-
-Here's the insight that changed everything:
-
-> **We designed tools as if humans would read the schemas. But LLMs read the schemas.**
-
-We thought about developer ergonomics: fewer tools, consistent naming, Unix-like. But LLMs don't care about those things. They care about:
-
-1. **Does the tool name match the user's intent?**
-2. **Are the parameters relevant to what I'm trying to do?**
-3. **Is the description clear about when to use this?**
-
----
-
-## The Key Insight: Users Speak, LLMs Choose
-
-When we observed actual usage, we saw this pattern:
-
-```
-User: "Clone the Sales SDR with its data and clean it up for demo"
-         │
-         ▼
-    LLM parses intent
-         │
-         ▼
-    LLM searches available tools
-         │
-         ▼
-    LLM selects: persona(mode="clone", from="...", include_data=true, sanitize=true)
-```
-
-The user never typed a tool name. They never selected from a menu. They just described what they wanted in natural language.
-
-**This means tool design is really about one thing: making it easy for LLMs to match natural language intent to the right tool with the right parameters.**
-
----
-
-## What About Prompts?
-
-MCP has two mechanisms: **Tools** and **Prompts**. We initially thought prompts could help—maybe `persona.create` as a prompt that guides the creation flow?
-
-But the MCP spec is clear about the distinction:
-
-| Mechanism | Who Controls | How Triggered |
-|-----------|--------------|---------------|
-| **Tools** | Model-controlled | LLM invokes automatically |
-| **Prompts** | User-controlled | User explicitly selects (slash commands) |
-
-Prompts are like slash commands (`/create_voice_ai`). They're for explicit, user-initiated workflows.
-
-**In practice, users rarely use slash commands.** They just talk. Which means tools are what matter for 95% of interactions.
-
-> **Design for natural language, not for slash commands. The LLM is the interface. Tools are the API.**
-
----
-
-## The Redesign
-
-### Principle 1: One Operation, One Tool
-
-Instead of modes, each operation gets its own tool:
-
-```typescript
-// Before: mode-based
-persona(mode="list")
-persona(mode="get", id="abc")
-persona(mode="create", name="Bot", ...)
-
-// After: operation-based
-persona()           // list (no params = list)
-persona(id="abc")   // get (id = get one)
-persona_create(name="Bot", ...)
-persona_clone(from="abc", ...)
-```
-
-Each tool has only the parameters relevant to that operation. When the LLM calls `persona_create`, it sees 5 relevant parameters, not 30.
-
-### Principle 2: Names Match Natural Language
-
-Tool names should match how users describe their intent:
-
-| User Says | Tool Name |
-|-----------|-----------|
-| "show me my personas" | `persona` |
-| "create a voice AI" | `persona_create` |
-| "clone it with data" | `persona_clone` |
-| "what's wrong with it" | `persona_analyze` |
-| "push to staging" | `sync_run` |
-
-The LLM matches "clone it with data" to `persona_clone(include_data=true)` because the tool name and flag names align with natural language.
-
-### Principle 3: Flags for Common Combinations
-
-Users often want compound operations: "clone with data AND sanitize." Instead of requiring multiple tool calls, common combinations become flags:
-
-```typescript
-persona_clone(
-  from: "abc",
-  name: "Demo Copy",
-  include_data: true,   // Clone data files too
-  sanitize: true        // Remove PII
-)
-```
-
-This handles 80% of cases in one call. For the other 20%, the LLM can chain tools.
-
-### Principle 4: Hierarchy in Names
-
-Data and workflows are persona-specific. The naming reflects this:
-
-```
-persona                      # list/get personas
-persona_create               # create
-persona_clone                # clone
-
-persona_data                 # list data for a persona
-persona_data_upload          # upload to a persona
-persona_data_sanitize        # sanitize data only
-
-persona_workflow             # get workflow
-persona_workflow_modify      # modify workflow
-persona_workflow_sanitize    # sanitize workflow only
-```
-
-This makes scope explicit: `persona_sanitize` does everything, `persona_data_sanitize` does just the data.
-
-### Principle 5: Cross-Platform Compatibility
-
-We almost used dot notation (`persona.data.upload`) because it looks cleaner and the MCP spec allows it. Then we discovered:
-
-| Spec | Allows Dots? |
-|------|--------------|
-| MCP | Yes (`admin.tools.list` is valid) |
-| OpenAI API | No (`^[a-zA-Z0-9_-]+$`) |
-
-Many MCP clients bridge to OpenAI-compatible APIs. Dot notation would break those integrations. **Snake case (`_`) is the safe choice.**
-
----
-
-## The Result
-
-### Before: 7 Tools, 30+ Params Each
-
-```
-persona(mode, id, name, type, from, input, include_data, sanitize, fix, include, ...)
-data(persona_id, mode, file_id, file, ...)
-action(id, all, query, category, suggest, ...)
-...
-```
-
-### After: 20 Focused Tools
-
-```
-# Core
-persona                     persona_create              persona_clone
-persona_update              persona_analyze             persona_sanitize
-
-# Data (persona-scoped)
-persona_data                persona_data_upload         persona_data_generate
-persona_data_delete         persona_data_sanitize
-
-# Workflow (persona-scoped)
-persona_workflow            persona_workflow_modify     persona_workflow_sanitize
-
-# Versions
-persona_version             persona_version_create      persona_version_restore
-
-# Other
-action                      action_suggest
-sync_run                    sync_status
-env
-```
-
-Each tool has 3-8 parameters. The LLM sees only what's relevant.
-
----
-
-## Key Takeaways
-
-### 1. Design for LLM Selection, Not Human Browsing
-
-Your tool names and descriptions are an API for LLMs. They need to match natural language patterns so the LLM can find the right tool when the user says "clone this and clean it up."
-
-### 2. Users Speak Natural Language, Not Slash Commands
-
-Prompts (user-triggered workflows) are a nice-to-have. Tools (model-selected operations) are the core experience. Invest accordingly.
-
-### 3. Fewer Parameters Beats Fewer Tools
-
-A tool with 30 parameters is harder for an LLM to use correctly than 5 tools with 6 parameters each. The LLM has to filter out irrelevant options with every call.
-
-### 4. Flag Names Are Natural Language
-
-When you name a flag `include_data`, you're not just documenting—you're making it matchable to "with data" or "include the files." Name flags like users talk.
-
-### 5. Interoperability Matters
-
-The MCP spec is flexible, but your tools might be bridged to OpenAI, Anthropic, or other APIs. Stick to the common denominator: alphanumeric plus underscore and hyphen.
-
----
-
-## The Mental Model
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  USER                                                           │
-│  "Clone the sales bot with data and sanitize for demo"         │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  LLM                                                            │
-│  Parses intent → Searches tools → Matches parameters           │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  TOOL SELECTION                                                 │
-│  persona_clone(from="sales-bot", name="Demo", include_data=true,│
-│                sanitize=true)                                   │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  MCP SERVER                                                     │
-│  Executes operation → Returns result                           │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-The user never sees tool names. The LLM is the interface. **Design your tools for the LLM, and the LLM will serve the user.**
-
----
-
-## References
-
-- [MCP Specification - Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
-- [MCP Specification - Prompts](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts)
-- [Awesome MCP Servers](https://mcpservers.org/) - Industry patterns
-- [Playwright MCP](https://github.com/microsoft/playwright-mcp) - Reference implementation
-
----
-
-*Have thoughts on MCP tool design? We'd love to hear what patterns work for you.*

package/docs/data-architecture.md

@@ -1,166 +0,0 @@
-# Data Architecture & Sourcing Strategy
-
-> **Principle**: MCP serves all data. Cursor rules are policy/flow only.
-
----
-
-## Data Sourcing Hierarchy
-
-For any data that MCP exposes, follow this resolution order:
-
-```
-1. Ema API (live, authoritative)      ← PREFERRED
-2. resources/** (repo files)          ← FILE FALLBACK  
-3. src/sdk/*.ts (embedded constants)  ← CODE FALLBACK
-4. NEVER: .cursor/rules/**            ← POLICY ONLY, NO DATA
-```
-
----
-
-## Current State Audit
-
-### ✅ DYNAMIC (API-First)
-
-| Resource | Source | Fallback | Notes |
-|----------|--------|----------|-------|
-| `ema://catalog/agents` | `listActions()` API | `AGENT_CATALOG` | Cached 60s, env-aware |
-| `ema://catalog/agents-summary` | `listActions()` API | `AGENT_CATALOG` | Markdown format |
-| `ema://catalog/templates` | `getPersonaTemplates()` API | Empty (use file-backed) | Cached 60s, env-aware |
-| `ema://catalog/templates-summary` | `getPersonaTemplates()` API | Empty | Markdown format |
-| `action(...)` tool | `listActions()` API | Embedded docs | Full API integration |
-
-### ⚠️ HARDCODED (Embedded in Code)
-
-| Resource | Source | Can Be Dynamic? | Priority |
-|----------|--------|-----------------|----------|
-| `ema://catalog/patterns` | `WORKFLOW_PATTERNS` | Yes - could query "template personas" | Medium |
-| `ema://catalog/widgets` | `WIDGET_CATALOG` | Yes - could query API | Low |
-| `ema://rules/input-sources` | `INPUT_SOURCE_RULES` | Unlikely - validation logic | Low |
-| `ema://rules/anti-patterns` | `ANTI_PATTERNS` | Unlikely - validation logic | Low |
-| `ema://rules/optimizations` | `OPTIMIZATION_RULES` | Unlikely - validation logic | Low |
-
-### 📁 FILE-BACKED (Repo Files - Fallback)
-
-| Resource | Path | Notes |
-|----------|------|-------|
-| `ema://templates/voice-ai/*` | `resources/templates/voice-ai/` | Fallback when API unavailable |
-| `ema://templates/chat-ai/*` | `resources/templates/chat-ai/` | Fallback when API unavailable |
-| `ema://templates/dashboard-ai/*` | `resources/templates/dashboard-ai/` | Fallback when API unavailable |
-| `ema://docs/*` | `docs/*.md` | Repo documentation |
-
-**Note**: For templates, prefer `ema://catalog/templates` (API-first) over file-backed `ema://templates/*`.
-
----
-
-## Making More Things Dynamic
-
-### ✅ DONE: Templates
-
-Templates are now API-first via `getPersonaTemplates()`:
-
-```typescript
-// EmaClient method
-async getPersonaTemplates(): Promise<PersonaTemplateDTO[]>
-
-// MCP Resources (API-first with cache)
-ema://catalog/templates          // Full template data
-ema://catalog/templates-summary  // Markdown summary
-```
-
-### Medium Priority: Workflow Patterns
-
-Patterns could be derived from analyzing existing personas:
-
-```typescript
-// Future: Pattern extraction from existing personas
-async function getPatterns() {
-  // 1. Query personas tagged as "template" or "pattern"
-  const templatePersonas = await client.getPersonasWithTag("template");
-  if (templatePersonas.length > 0) {
-    return extractPatternsFromPersonas(templatePersonas);
-  }
-  
-  // 2. Fallback to embedded patterns
-  return WORKFLOW_PATTERNS;
-}
-```
-
-### Low Priority: Validation Rules
-
-These are internal logic, not external data. Keep embedded unless Ema provides a validation API.
-
----
-
-## Where Data Lives
-
-```
-ema-mcp-toolkit/
-├── src/
-│   ├── mcp/
-│   │   ├── resources.ts        # Resource registry + dynamic fetching
-│   │   ├── server.ts           # Tool handlers (API calls)
-│   │   └── prompts.ts          # Prompt definitions (structured guidance)
-│   └── sdk/
-│       ├── client.ts           # EmaClient (API wrapper)
-│       ├── knowledge.ts        # AGENT_CATALOG, WORKFLOW_PATTERNS, WIDGET_CATALOG
-│       └── validation-rules.ts # INPUT_SOURCE_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES
-├── resources/
-│   └── templates/              # File-backed templates (canonical location)
-│       ├── voice-ai/
-│       ├── chat-ai/
-│       └── dashboard-ai/
-└── .cursor/
-    └── rules/                  # POLICY/FLOW ONLY - NO DATA
-        ├── base/naming/        # Naming conventions
-        ├── ema/                # MCP usage guidance
-        └── platforms/ema/      # Platform-specific flows
-```
-
----
-
-## Cursor Rules Policy
-
-### ✅ ALLOWED in Cursor Rules
-
-- **Process flows**: "How to create an AI Employee"
-- **Decision trees**: "When to use HITL"
-- **Tool usage guidance**: "Use `workflow(mode='analyze')` for..."
-- **References to MCP**: "Fetch from `ema://catalog/agents`"
-- **Best practices**: "Always extract email recipients via entity_extraction"
-
-### ❌ NOT ALLOWED in Cursor Rules
-
-- **Agent definitions**: Use `ema://catalog/agents`
-- **Template content**: Use `ema://templates/*`
-- **Validation rules data**: Use `ema://rules/*`
-- **Hardcoded patterns**: Use `ema://catalog/patterns`
-- **Any data that can change**: Must come from MCP
-
----
-
-## Implementation Checklist
-
-### Already Done ✅
-
-- [x] Agent catalog is API-first (`getDynamicAgentCatalog()`)
-- [x] Templates moved from `.cursor/` to `resources/`
-- [x] `action(...)` tool uses API with docs fallback
-- [x] Resources support `?env=` parameter
-- [x] **Persona templates are API-first** (`getDynamicPersonaTemplates()`)
-- [x] Added `EmaClient.getPersonaTemplates()` method
-- [x] Added `ema://catalog/templates` and `ema://catalog/templates-summary` resources
-
-### To Do (Future)
-
-- [ ] Extract workflow patterns from template `workflow_definition` fields
-- [ ] Consider caching strategy improvements (longer TTL for stable data)
-- [ ] Add health check for API availability
-
----
-
-## Related Documentation
-
-- `docs/mcp-tools-guide.md` - Tool usage
-- `docs/naming-conventions.md` - Naming standards
-- `.cursor/rules/base/naming/RULE.md` - Naming enforcement
-- `.cursor/rules/ema/RULE.md` - MCP source-of-truth policy