@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/dist/mcp/knowledge-guidance-topics.js

@@ -36,13 +36,13 @@ export const GUIDANCE_TOPICS = {
         examples: [
             "✅ trigger.user_query → search.query (TEXT_WITH_SOURCES → TEXT_WITH_SOURCES)",
             "❌ trigger.chat_conversation → search.query (CHAT_CONVERSATION ≠ TEXT_WITH_SOURCES)",
-            "✅ search.search_results → respond_for_external_actions.external_action_result (SEARCH_RESULT → ANY)",
+            "✅ search.search_results → call_llm.named_inputs_Search_Results (SEARCH_RESULT → ANY via named_inputs)",
             "❌ search.search_results → call_llm.query (SEARCH_RESULT ≠ TEXT_WITH_SOURCES)",
             "✅ search.search_results → call_llm.named_inputs_* (SEARCH_RESULT → ANY)",
         ],
         criticalRules: [
             "CHAT_CONVERSATION only compatible with chat_categorizer.conversation",
-            "SEARCH_RESULT compatible with respond_for_external_actions.external_action_result or named_inputs (respond_with_sources/v0 is deprecated)",
+            "SEARCH_RESULT → call_llm.named_inputs (most common), respond_with_sources.search_results, or any node accepting ANY",
             "call_llm.named_inputs accepts ANY type",
             "Use conversation_to_search_query to convert CHAT_CONVERSATION → TEXT_WITH_SOURCES",
         ],
@@ -61,26 +61,32 @@ export const GUIDANCE_TOPICS = {
     },
     "hitl-patterns": {
         title: "Human-in-the-Loop Patterns",
-        content: "HITL is implemented as a FLAG on specific agents — ONLY entity_extraction_with_documents and send_email_agent support it. " +
-            "external_action_caller does NOT support HITL. general_hitl is NOT deployable (appears in catalogs but cannot be deployed). " +
-            "When the user requests approval, enable the HITL flag on send_email_agent or entity_extraction_with_documents. " +
-            "The platform handles the approval UI and routing automatically.\n\n" +
-            "JSON format: Set `disable_human_interaction: false` (or omit — default is false = HITL enabled) on the action node " +
-            "in workflow_def.actions[]. To DISABLE HITL, set `disable_human_interaction: true`. " +
-            "Note the counter-intuitive naming: false = HITL ON, true = HITL OFF.",
+        content: "Two HITL mechanisms:\n\n" +
+            "1. **general_hitl (Human Collaboration Agent)**: Standalone node with three modes — " +
+            "Conversational (back-and-forth dialogue with success/failure criteria), " +
+            "Standard Form (structured fields: string, number, boolean, multi-select), " +
+            "Custom Form (external hosted form URL). Outputs: human_collaboration_status (HITL Success/Failure enum) " +
+            "and summarized_conversation. Branch downstream with runIf.\n\n" +
+            "2. **Agent-level HITL flags**: entity_extraction_with_documents and send_email_agent support " +
+            "`disable_human_interaction: false` for simple yes/no approval on their own action. " +
+            "The platform handles the approval UI automatically.\n\n" +
+            "JSON format: Set `disable_human_interaction: false` on the action node " +
+            "in workflow_def.actions[]. Note: false = HITL ON, true = HITL OFF.",
         status: "verified",
         examples: [
-            "User wants email approval → enable HITL flag on send_email_agent",
-            "User wants extraction review → enable HITL flag on entity_extraction_with_documents",
-            "JSON: { name: 'send_email', action: { name: 'send_email_agent' }, disable_human_interaction: false, ... } → HITL ENABLED",
-            "JSON: { name: 'respond', action: { name: 'call_llm' }, disable_human_interaction: true, ... } → HITL DISABLED (auto-proceed)",
+            "Complex approval dialogue → general_hitl (Conversational mode, define success/failure criteria)",
+            "Collect structured data from user → general_hitl (Standard Form mode)",
+            "Simple email send approval → send_email_agent with disable_human_interaction: false",
+            "Review extraction before acting → entity_extraction_with_documents with disable_human_interaction: false",
+            "JSON: { name: 'review', action: { name: 'general_hitl' }, ... } → standalone HITL node",
         ],
         criticalRules: [
-            "general_hitl is NOT deployable — do NOT add it to any workflow",
-            "HITL is ONLY supported on: entity_extraction_with_documents and send_email_agent",
-            "external_action_caller does NOT support HITL despite appearing in older guidance",
-            "JSON field: `disable_human_interaction` (boolean) on the action node — false=HITL on, true=HITL off",
-            "When user says 'with approval': set disable_human_interaction: false on send_email_agent or entity_extraction_with_documents",
+            "general_hitl IS deployable — it's a full Human Collaboration Agent with 3 modes",
+            "For rich dialogue/forms: use general_hitl (Conversational, Standard Form, Custom Form)",
+            "For simple approval: use HITL flag on send_email_agent or entity_extraction_with_documents",
+            "external_action_caller does NOT support HITL",
+            "JSON field: `disable_human_interaction` (boolean) on agent-level HITL — false=HITL on, true=HITL off",
+            "general_hitl max_exchanges prevents infinite loops (default 5). Exceeding max = HITL Failure.",
         ],
     },
     "hitl-policy": {
@@ -103,16 +109,16 @@ export const GUIDANCE_TOPICS = {
     },
     "multi-source-search": {
         title: "Multi-Source Search Architecture",
-        content: "For comprehensive answers, combine local search with web search. Use combine_search_results to merge and deduplicate.",
+        content: "For comprehensive answers, combine local search with web search. Use combine_and_rerank_search_results to merge and rerank by relevance. Alternatively, use call_llm with multiple named_inputs to combine results with prompt-based ranking.",
         status: "verified",
         examples: [
-            "search (local) + live_web_search → combine_search_results → respond_for_external_actions",
-            "For cross-document linking: entity_extraction → knowledge_graph_generator → document_synthesis",
+            "search (local) + live_web_search → combine_and_rerank_search_results → call_llm",
+            "search (local) + live_web_search → call_llm.named_inputs_KB_Results + call_llm.named_inputs_Web_Results",
         ],
         criticalRules: [
-            "Use entity extraction when cross-document linking is needed",
-            "Use LLM resolution for single conversational queries",
-            "Entity extraction requires schema definition",
+            "combine_and_rerank_search_results reranks by relevance — use when you need weighted/prioritized results",
+            "call_llm with named_inputs gives prompt-level control over how results are synthesized",
+            "Single search node can handle multiple datastores via datastore_configs",
         ],
     },
     "voice-tool-calling": {
@@ -404,7 +410,9 @@ export const GUIDANCE_TOPICS = {
 - NO → Use transform node (json_mapper, fixed_response)
 
 ### Q3: What KIND of generation?
-- Simple Q&A with citations → respond_for_external_actions
+- KB Q&A → call_llm with search results via named_inputs (most common, 89% of production)
+- KB Q&A with automatic citations → respond_with_sources
+- Explain external tool results → respond_for_external_actions
 - Custom generation → call_llm
 - Complex multi-step reasoning → custom_agent
 - Search + synthesize in one → document_synthesis
@@ -420,26 +428,29 @@ export const GUIDANCE_TOPICS = {
 | fixed_response | 0 | <50ms | Static content, config, templates |
 | json_mapper | 0 | <100ms | Transform JSON without reasoning |
 | entity_extraction | 1 | 1-2s | Extract structured data |
-| respond_for_external_actions | 1 | 2-4s | Search + response (conversation-aware) |
-| call_llm | 1 | 2-4s | Custom generation |
+| call_llm | 1 | 2-4s | Custom generation, KB Q&A with named_inputs |
+| respond_with_sources | 1 | 2-4s | Citation-grounded search response |
+| respond_for_external_actions | 1 | 2-4s | Explain external tool results ONLY |
 | custom_agent | 1-3 | 3-8s | Complex reasoning |
 | document_synthesis | 2-5 | 5-15s | Multi-search + synthesis |`,
         examples: [
             "✅ Static template → fixed_response (0 LLM calls)",
             "✅ Extract client_name, email → entity_extraction (1 LLM call, typed output)",
-            "✅ Simple KB Q&A → respond_for_external_actions (1 LLM call, conversation-aware)",
+            "✅ KB Q&A → search → call_llm.named_inputs_Search_Results (most common)",
             "✅ Custom email generation → call_llm with search results in named_inputs",
+            "✅ Explain Salesforce API result → respond_for_external_actions",
             "❌ Using call_llm to extract JSON → Use entity_extraction instead",
-            "❌ Using document_synthesis for simple Q&A → Use respond_for_external_actions",
+            "❌ Using document_synthesis for simple Q&A → Use call_llm with named_inputs",
+            "❌ Using respond_for_external_actions for KB Q&A → It's for tool results only",
             "❌ Using custom_agent for static response → Use fixed_response",
         ],
         criticalRules: [
             "NEVER use LLM for transforms that json_mapper can do",
             "NEVER use call_llm for structured extraction - use entity_extraction",
-            "NEVER use document_synthesis when respond_for_external_actions suffices",
+            "NEVER use respond_for_external_actions for KB Q&A — it's ONLY for external_action_caller results",
             "ALWAYS use fixed_response for static content (templates, config, help text)",
-            "Use entity_extraction for typed, reliable structured data",
-            "Use call_llm when you need custom instructions or reasoning",
+            "Use call_llm with named_inputs for most post-search generation (89% of production)",
+            "Use respond_with_sources for citation-grounded responses",
             "Use custom_agent when task requires role context + multi-step reasoning",
             "Use document_synthesis only when you need search-plan-search-synthesize pattern",
         ],
@@ -447,23 +458,28 @@ export const GUIDANCE_TOPICS = {
     "llm-node-selection": {
         title: "LLM Node Selection: Which One to Use",
         status: "verified",
-        content: `Different LLM nodes serve different purposes. Choose based on your needs:
+        content: `Different generation nodes serve different purposes. Choose based on your needs:
 
-## respond_for_external_actions (replaces deprecated respond_with_sources)
-- **Best for**: Simple Q&A with KB citations, tool result explanation
-- **Input**: Search results or tool results via external_action_result
-- **Output**: Response with source citations
-- **When**: User asks question, you search KB, return answer
-- **NOT for**: Custom generation, complex reasoning
-
-## call_llm
-- **Best for**: Custom text generation with instructions
-- **Input**: Query + optional search/context via named_inputs
+## call_llm (Respond) — Default choice for most generation
+- **Best for**: KB Q&A, custom text generation, content synthesis
+- **Input**: Query + optional search/context/anything via named_inputs
 - **Output**: Generated text
-- **When**: Need custom prompts, specific format, controlled generation
-- **NOT for**: Simple Q&A (use respond_for_external_actions)
+- **When**: Most common post-search node (89% of production). Use for KB Q&A, email drafting, document content.
+- **Key feature**: named_inputs accepts ANY type — wire search results, tool outputs, etc.
+
+## respond_with_sources — Citation-grounded search responses
+- **Best for**: Responses that need automatic source citations
+- **Input**: Query + search_results (requires SEARCH_RESULT type)
+- **Output**: Response with citations
+- **When**: You specifically need citation-based filtering and source attribution
+
+## respond_for_external_actions — Explain external tool results ONLY
+- **Best for**: Explaining results from external_action_caller (Salesforce, ServiceNow, etc.)
+- **Input**: Query + external_action_result from external_action_caller
+- **Output**: Human-friendly explanation of tool results
+- **ONLY use after**: external_action_caller. NOT for KB Q&A, NOT for search results.
 
-## custom_agent
+## custom_agent — Complex multi-step reasoning
 - **Best for**: Complex tasks requiring role + instructions
 - **Input**: Role instructions + task instructions + named_inputs
 - **Output**: Structured or free-form response (use output_fields for structured)
@@ -471,25 +487,26 @@ export const GUIDANCE_TOPICS = {
 - **NOT for**: Simple generation (overkill)
 - **CRITICAL**: When outputting JSON for json_mapper, use output_fields to define keys
 
-## document_synthesis
+## document_synthesis — Multi-source research
 - **Best for**: Multi-source research with planning
 - **Input**: User request + search results
 - **Output**: Synthesized document
 - **When**: Need to search → plan → search again → synthesize
 - **NOT for**: Simple KB lookup (too heavy)`,
         examples: [
-            "User asks 'What is our refund policy?' → respond_for_external_actions",
-            "Need to generate email with specific template → call_llm",
+            "User asks 'What is our refund policy?' → search → call_llm.named_inputs_Search_Results",
+            "Need to generate email with specific template → call_llm with structured prompt",
+            "Salesforce lookup result → respond_for_external_actions to explain to user",
             "Need to analyze portfolio and recommend actions → custom_agent",
             "Need to research topic across multiple sources → document_synthesis",
         ],
         criticalRules: [
-            "respond_for_external_actions: 1 LLM call, simple Q&A or tool results, conversation-aware",
-            "call_llm: 1 LLM call, custom generation, accepts named_inputs",
+            "call_llm: Default for KB Q&A and most generation. 1 LLM call, accepts named_inputs of ANY type",
+            "respond_with_sources: For citation-grounded responses from search results",
+            "respond_for_external_actions: ONLY after external_action_caller — NOT for KB Q&A",
             "custom_agent: 1-3 LLM calls, complex reasoning, has role context",
             "document_synthesis: 2-5 LLM calls, heavy, only for research tasks",
-            "Default to respond_for_external_actions for KB Q&A",
-            "Upgrade to call_llm when you need custom instructions",
+            "Default to call_llm for most post-search generation",
             "Upgrade to custom_agent for complex reasoning",
             "Use document_synthesis sparingly (latency expensive)",
         ],
@@ -612,4 +629,24 @@ json_mapper outputs go to output_json. Use fixed_response template variables:
             "Default values in json_mapper rules prevent null errors",
         ],
     },
+    "feedback-probes": {
+        title: "Feedback Probes and Telemetry Collection",
+        content: `Tool responses may include a _probe field with a targeted question about your experience. Responding to probes helps improve specific areas of the toolkit.
+
+To respond to a probe, use:
+toolkit_feedback(method="submit", category="probe_response", message="<your answer>", context="<probe.id>")
+
+The toolkit also collects anonymous telemetry (tool usage, error rates, latency) to identify patterns. This data is coalesced locally and periodically uploaded as a digest. Set EMA_FEEDBACK_DISABLED=1 to opt out of all remote collection.`,
+        status: "verified",
+        examples: [
+            'toolkit_feedback(method="submit", category="probe_response", message="Workflow deploy was confusing because...", context="workflow-deploy-confidence-2026q1")',
+            'toolkit_feedback(method="submit", category="gap", message="No docs on how to wire email inputs")',
+        ],
+        criticalRules: [
+            "When a _probe appears in a tool response, respond via toolkit_feedback with category='probe_response'",
+            "Include the id from the _probe field as the context parameter",
+            "Probes are optional — skip if not relevant to your current task",
+            "Regular feedback (gap, confusion, success, error_unclear, suggestion) can be submitted anytime",
+        ],
+    },
 };