# RevCent MCP Operation: `CreateAIVoiceSnippet` This document explains the `CreateAIVoiceSnippet` operation in depth so MCP clients can correctly create AI Voice Snippets in RevCent. This is an operation-specific MCP guide. It explains required fields, naming rules, Handlebars behavior, snippet usage in AI Voice Agent instructions, examples, validation rules, and common mistakes. Sources: - RevCent API/MCP schema for `CreateAIVoiceSnippet` - RevCent Knowledge Base: [AI Voice Agents — AI Voice Snippets](https://kb.revcent.com/en/tools/ai/voice-agents#ai-voice-snippets) --- ## Operation Summary `CreateAIVoiceSnippet` creates an AI Voice Snippet and returns a unique `ai_voice_snippet_id`. An AI Voice Snippet is reusable instruction content for AI Voice Agents. Main purpose: ```text Create reusable instruction blocks that can be used across multiple AI Voice Agents. ``` A snippet can be referenced in main AI Voice Agent instructions using: ```handlebars {{snippets.snippet_name}} ``` Example: ```handlebars {{snippets.card_guidelines}} ``` --- --- # When MCP Should Create an AI Voice Snippet MCP should not create AI Voice Snippets by default. AI Voice Snippets should mainly be created when the user has **multiple AI Voice Agents** and a shared instruction block is used across those agents and is likely to change frequently. The main reason to create a snippet is maintainability. Good reasons to create a snippet: ```text The same instruction block is used by many AI Voice Agents. The instruction block changes often. The user wants one central place to update shared behavior. The snippet reduces duplicated editing. The snippet makes behavior more consistent across agents. ``` Examples: ```text Card collection rules shared by multiple payment recovery agents. Caller verification rules shared by multiple inbound support agents. Transfer rules shared by all customer-facing agents. Compliance language shared by many agents. Refund boundaries shared by many support agents. Chargeback escalation rules shared by multiple risk/support agents. ``` --- ## When MCP Should Prefer Direct AI Voice Agent Instruction Edits If the user has fewer than about **5 AI Voice Agents**, it is usually better to modify the AI Voice Agent instructions directly instead of creating a snippet. Direct instruction edits are often better for smaller setups because: - The full agent behavior is visible in one instruction document. - There is less indirection. - The user can review the agent more easily. - MCP clients do not need to resolve snippet references to understand the agent. - A shared snippet cannot accidentally change multiple agents. - The user may not have enough repeated content to justify snippet maintenance. Recommended rule: ```text If the user has fewer than 5 AI Voice Agents, prefer direct instruction edits unless the user clearly has shared instruction text that is reused and frequently changed. ``` --- ## MCP Decision Rule Before calling `CreateAIVoiceSnippet`, MCP should ask or determine: ```text Will this snippet be used by multiple AI Voice Agents? Will the shared instruction statement change frequently? Would a snippet reduce maintenance work? Would direct instruction edits be clearer? Does the user have enough agents to justify a snippet? ``` Create a snippet only when the snippet makes the system easier to maintain. Do not create snippets merely because a piece of instruction text could technically be reused. # Required Fields | Field | Type | Required | Description | |---|---:|---:|---| | `name` | string | Yes | Unique AI Voice Snippet name. Must follow strict naming rules. | | `content` | string | Yes | Snippet content. Can contain Markdown and Handlebars syntax. | --- # Optional Fields | Field | Type | Required | Description | |---|---:|---:|---| | `description` | string | No | Description of what the snippet is for and where it should be used. | | `enabled` | boolean | No | Whether the AI Voice Snippet is enabled. | The schema has: ```json "additionalProperties": false ``` Do not send unknown fields. --- # `name` The `name` is extremely important because it is used as the key inside the `snippets` object. Example: ```json { "name": "card_guidelines" } ``` Usage in AI Voice Agent instructions: ```handlebars {{snippets.card_guidelines}} ``` --- ## Name Rules The name must: - Contain alphabetical characters or underscores only. - Have a minimum length of 2. - Have a maximum length of 100. - Be unique across all AI Voice Snippets in the account. - Not start with an underscore. - Not end with an underscore. Allowed: ```text card_guidelines refund_policy caller_verification transfer_rules subscription_cancellation chargeback_escalation shipping_support payment_recovery_tone ``` Not allowed: ```text card-guidelines card guidelines card.guidelines _card_guidelines card_guidelines_ card123 a ``` Because snippet names are used in Handlebars, use clear underscore-separated names. --- ## Naming Best Practices Use names that describe the reusable instruction purpose. Good: ```text card_guidelines refund_policy caller_verification transfer_rules end_call_rules ``` Poor: ```text snippet test rules content voice ``` The name should be stable because existing AI Voice Agent instructions may reference it. Changing names later can require updating agent instructions that reference the old snippet name. --- # `description` The description should explain: - What the snippet does - Which agents should use it - Which agents should not use it - Whether it assumes certain system actions are enabled - Whether it contains policy, compliance, payment, refund, subscription, or transfer rules Example: ```json { "description": "Reusable card collection guidelines for AI Voice Agents that are allowed to collect card information through AddCardToCustomer." } ``` Descriptions are highly recommended because snippets can be reused across many agents and may affect customer-facing calls. --- # `enabled` `enabled` controls whether the snippet is active. The KB explains that the `snippets` object contains the compiled content of enabled AI Voice Snippets. Recommended behavior: ```text Create a snippet disabled first if it still needs review. Enable it only after content is approved. ``` Example: ```json { "enabled": false } ``` If a snippet is disabled, do not rely on it being available in the main agent instructions. --- # `content` `content` is the reusable instruction content. It can contain: - Markdown headings - Bullet lists - Conversation rules - Safety boundaries - Handlebars syntax - Custom helpers such as `toString` - Conditional rendering - References to `agent`, `item`, `customer`, and `pre_agent_function` Example: ```json { "content": "# Customer Card Guidelines\n- Be patient while the caller gives card information.\n- Do not interrupt the caller while they are reciting their card number.\n- Only collect card information if the customer clearly agrees." } ``` --- # Snippet Content Compiles With Handlebars AI Voice Snippets compile like main AI Voice Agent instructions. They can use the same Handlebars data the main AI Voice Agent instructions receive when compiling, except for the `snippets` object. Available data may include: ```text call_method agent item customer pre_agent_function ``` Custom helpers can include: ```text toString ifEquals ``` Important: ```text The snippets object is only available in the main AI Voice Agent instructions, not inside individual snippet compilation. ``` Do not reference snippets from inside snippet content. Wrong inside a snippet: ```handlebars {{snippets.other_snippet}} ``` Correct inside main AI Voice Agent instructions: ```handlebars {{snippets.card_guidelines}} ``` --- # Accessing a Snippet in Main Agent Instructions After creating an enabled snippet named: ```text card_guidelines ``` use it in the main AI Voice Agent instructions as: ```handlebars {{snippets.card_guidelines}} ``` If the snippet is named: ```text refund_policy ``` use: ```handlebars {{snippets.refund_policy}} ``` --- # Good Snippet Content Patterns ## Card Guidelines ```markdown # Customer Card Guidelines - Be patient while the caller provides card information. - Do not interrupt the caller while they are reciting card details. - Only collect card information if the caller clearly agrees. - Do not repeat full card numbers back to the caller. ``` ## Caller Verification ```handlebars # Caller Verification Rules {{#if customer.verified}} - Customer context may be available, but still follow the verification rules before discussing private account details. {{else}} - Do not assume the caller is an existing customer. - Ask for identifying information and use search actions only if enabled. {{/if}} ``` ## Brand Voice From Pre-Agent Function ```handlebars # Brand Voice {{#if pre_agent_function.response.company_name}} - Identify as {{pre_agent_function.response.company_name}} customer support. {{else}} - Identify as customer support. {{/if}} ``` ## Product List From Pre-Agent Function ```handlebars # Available Products {{#if pre_agent_function.response.product_list}} {{{toString pre_agent_function.response.product_list}}} {{else}} - No dynamic product list was provided for this call. {{/if}} ``` ## Transfer Rules ```markdown # Transfer Rules - If the caller asks for a human, representative, supervisor, or manager, offer to transfer. - Do not argue with the caller about speaking to a human. - If transfer fails, apologize and follow the agent's fallback instructions. ``` --- # What Snippet Content Should Not Do A snippet should not be a full AI Voice Agent instruction document. Avoid creating snippets that define everything: ```text Role Objective Full conversation flow All system action behavior All payment/refund/subscription rules All escalation logic ``` Those belong in the main AI Voice Agent instructions. A snippet should be a reusable module. --- # Snippets and System Actions Snippets are instruction text only. Creating a snippet does not enable any system action. If a snippet says: ```markdown - Retrieve the customer shipment. ``` the AI can only do that if the main AI Voice Agent has the appropriate system action enabled. Therefore, MCP should avoid creating snippets that assume system actions unless: 1. The snippet is clearly intended only for agents with those actions enabled. 2. The description says which system actions are expected. 3. The content includes safe fallback behavior. --- # Snippets and Pre-Agent Functions Snippets can reference pre-agent Function responses. Pre-agent Function data is available under: ```text pre_agent_function.response ``` Example: ```handlebars {{#if pre_agent_function.response.company_name}} - Use {{pre_agent_function.response.company_name}} as the brand name. {{/if}} ``` For arrays/objects, use triple curly braces with `toString`: ```handlebars {{{toString pre_agent_function.response.product_list}}} ``` --- # MCP Creation Process Before calling `CreateAIVoiceSnippet`, MCP should determine: 1. What reusable instruction content is needed? 2. Does the user have multiple AI Voice Agents, preferably 5 or more, where a shared snippet is actually useful? 3. Which agents will use this snippet? 3. What should the snippet name be? 4. Does the name follow the allowed naming rules? 5. Is the content focused on one reusable topic? 6. Does the content contain Handlebars? 7. If using Handlebars, are optional values guarded with `{{#if ...}}`? 8. Does the content reference `pre_agent_function.response.*` correctly? 9. Does the content avoid referencing `snippets.*` inside the snippet? 10. Does the content assume system actions? 11. If it assumes system actions, is that clear in the description? 13. Would direct AI Voice Agent instruction edits be clearer than creating a snippet? 14. Should the snippet be created disabled for review or enabled immediately? --- # Example Request: Card Guidelines Snippet ```json { "name": "card_guidelines", "description": "Reusable card collection guidelines for AI Voice Agents that are allowed to collect or add customer cards.", "enabled": true, "content": "# Customer Card Guidelines\n- Be patient while the caller provides card information.\n- Do not interrupt the caller while they are reciting card details.\n- Only collect card information if the caller clearly agrees.\n- Do not repeat full card numbers back to the caller." } ``` Usage in agent instructions: ```handlebars {{snippets.card_guidelines}} ``` --- # Example Request: Brand Voice Snippet ```json { "name": "brand_voice", "description": "Reusable brand identification rules. Uses pre_agent_function.response.company_name when available.", "enabled": true, "content": "# Brand Voice\n{{#if pre_agent_function.response.company_name}}\n- Identify as {{pre_agent_function.response.company_name}} customer support.\n{{else}}\n- Identify as customer support.\n{{/if}}" } ``` Usage: ```handlebars {{snippets.brand_voice}} ``` --- # Example Request: Transfer Rules Snippet ```json { "name": "transfer_rules", "description": "Reusable rules for transferring callers to a human when requested or required.", "enabled": true, "content": "# Transfer Rules\n- If the caller asks for a human, representative, supervisor, manager, or support agent, offer to transfer.\n- Do not argue with the caller.\n- If transfer fails, apologize and follow the agent's fallback instructions." } ``` Usage: ```handlebars {{snippets.transfer_rules}} ``` --- # Output Schema Successful response: ```json { "api_call_id": "XXXXXXXXXXXXXXXXXXXX", "api_call_unix": 1740000000, "code": 1, "ai_voice_snippet_id": "YYYYYYYYYYYYYYYYYYYY", "result": "..." } ``` | Field | Description | |---|---| | `api_call_id` | 20-character API call ID. | | `api_call_unix` | Unix timestamp when the API call was initiated. | | `code` | API response code. `1` indicates success. | | `ai_voice_snippet_id` | 20-character AI Voice Snippet ID created by the operation. | | `result` | Human-readable result message. | --- # Validation Checklist Before submitting `CreateAIVoiceSnippet`: 1. `name` is present. 2. `name` is 2 to 100 characters. 3. `name` contains only letters and underscores. 4. `name` does not start with an underscore. 5. `name` does not end with an underscore. 6. `name` is unique across AI Voice Snippets in the account. 7. `content` is present. 8. `content` is focused on reusable instruction content. 9. The user has multiple AI Voice Agents or a clear repeated instruction block that changes frequently. 9. `content` is not a full agent instruction replacement unless intentionally designed as a large reusable block. 10. Any Handlebars syntax is valid. 11. Optional data is guarded with `{{#if ...}}`. 12. Pre-agent data is referenced as `pre_agent_function.response.*`. 13. Objects/arrays use `{{{toString ...}}}` when embedded. 14. The snippet does not reference `snippets.*` inside its own content. 15. The description explains expected usage. 16. Any assumed system actions are documented in the description or content. 18. Direct AI Voice Agent instruction editing was considered and rejected because a snippet is truly useful. 19. `enabled` is set intentionally. --- # Common Mistakes ## Mistake: Using an Invalid Name Wrong: ```json { "name": "card-guidelines" } ``` Correct: ```json { "name": "card_guidelines" } ``` --- ## Mistake: Referencing Snippets Inside Snippets Wrong inside snippet content: ```handlebars {{snippets.transfer_rules}} ``` Correct in main agent instructions: ```handlebars {{snippets.transfer_rules}} ``` --- ## Mistake: Forgetting `pre_agent_function.response` Wrong: ```handlebars {{company_name}} ``` Correct: ```handlebars {{pre_agent_function.response.company_name}} ``` --- ## Mistake: Assuming Snippets Enable Tools A snippet can tell the AI what to do, but it does not enable the system action required to do it. System actions must be enabled on the AI Voice Agent itself. --- # Quick Reference Minimum request: ```json { "name": "card_guidelines", "content": "# Customer Card Guidelines\n- Be patient while the caller provides card information." } ``` Use in agent instructions: ```handlebars {{snippets.card_guidelines}} ``` Most important rules: ```text Snippet names become snippets.[name]. Use only letters and underscores. Do not start or end with underscore. Content can use Markdown and Handlebars. Use pre_agent_function.response.* for pre-agent data. Do not reference snippets.* inside snippet content. Snippets do not enable system actions. Use snippets for reusable instruction modules, not entire agent design. Prefer direct AI Voice Agent instruction edits when the user has fewer than 5 AI Voice Agents or the instruction is not frequently reused/changed. ``` --- Document Parent Directory * [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.