# RevCent MCP Operation: `EditAIVoiceSnippet`

This document explains the `EditAIVoiceSnippet` operation in depth so MCP clients can correctly update existing AI Voice Snippets in RevCent.

This is an operation-specific MCP guide. It explains partial edit behavior, required fields, editable properties, naming rules, content editing, Handlebars behavior, safety concerns, examples, validation rules, and common mistakes.

Sources:
- RevCent API/MCP schema for `EditAIVoiceSnippet`
- 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

`EditAIVoiceSnippet` edits a previously created AI Voice Snippet using the required `ai_voice_snippet_id`.

A snippet is reusable AI Voice Agent instruction content.

Important edit behavior:

```text
Only include the properties you wish to modify.
```

For example:

- If only changing the description, include only `ai_voice_snippet_id` and `description`.
- If only disabling the snippet, include only `ai_voice_snippet_id` and `enabled`.
- If changing content, include only `ai_voice_snippet_id` and `content`, unless other fields are intentionally being changed.

---

# Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `ai_voice_snippet_id` | string | Yes | 20-character AI Voice Snippet ID to edit. |

Minimal shape:

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

A real edit should include at least one additional field.

---

# Editable Fields

| Field | Type | Required | Description |
|---|---:|---:|---|
| `ai_voice_snippet_id` | string | Yes | 20-character AI Voice Snippet ID. |
| `name` | string | No | New snippet name. Must follow strict naming rules and remain unique. |
| `description` | string | No | Updated snippet description. |
| `enabled` | boolean | No | Whether the snippet is enabled. |
| `content` | string | No | Updated snippet content. Can contain Handlebars syntax. |

The schema has:

```json
"additionalProperties": false
```

Do not send unknown fields.

---

# Critical Edit Rule: Only Include Fields Being Modified

`EditAIVoiceSnippet` is a partial-update operation.

Correct name-only edit:

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "card_guidelines"
}
```

Correct enabled-only edit:

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": false
}
```

Correct content-only edit:

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "content": "# Customer Card Guidelines\n- Be patient while the caller provides card information."
}
```

Do not include fields unnecessarily.

---

# Why Editing Snippets Is High Impact

AI Voice Snippets can be reused across multiple AI Voice Agents.

Editing one snippet can change the compiled instructions for every AI Voice Agent that references it.

This means snippet edits can affect:

- Payment behavior
- Refund behavior
- Verification rules
- Transfer rules
- Tone and branding
- Subscription cancellation behavior
- Chargeback escalation behavior
- Shipping support behavior
- Compliance language
- End-call rules
- Customer experience across multiple agents

Because snippets are shared, MCP should treat snippet edits carefully.

---

---

# When MCP Should Edit a Snippet vs Edit Agent Instructions Directly

MCP should not assume that editing an AI Voice Snippet is always the best way to change AI Voice Agent behavior.

A snippet edit may affect every AI Voice Agent that references that snippet.

Because of that, snippet edits are best when the user has **multiple AI Voice Agents** using the same shared instruction block and that shared block is intentionally maintained centrally.

Good reasons to edit a snippet:

```text
The same snippet is used by multiple AI Voice Agents.
The user wants the same policy/rule updated across all those agents.
The instruction block changes frequently.
The snippet exists specifically to centralize that shared behavior.
The affected agents should all receive the same updated behavior.
```

Examples:

```text
Update shared card collection rules across several payment agents.
Update shared caller verification rules across several inbound agents.
Update shared transfer/escalation language across many agents.
Update shared compliance language used by all customer-facing voice agents.
```

---

## When Direct Agent Instruction Edits Are Safer

If the user has fewer than about **5 AI Voice Agents**, or if only one agent needs the change, it is usually better to edit the AI Voice Agent instructions directly instead of editing or creating a snippet.

Direct agent instruction edits are often safer because:

- The change affects only the intended agent.
- The full behavior remains visible in that agent’s instruction document.
- There is less hidden dependency on shared content.
- There is less risk of accidentally changing other agents.
- Review and testing are simpler.

Recommended rule:

```text
If the user has fewer than 5 AI Voice Agents, prefer editing the AI Voice Agent instructions directly unless the snippet is clearly shared by multiple agents and frequently changed.
```

---

## High-Risk Snippet Edit Warning

Before editing snippet `content`, MCP should consider:

```text
Which agents reference this snippet?
Should all of those agents receive this change?
Would any agent become incorrect or unsafe after the snippet changes?
Would it be safer to edit one agent directly?
```

If the change is agent-specific, do not edit the snippet.

Instead, edit the relevant AI Voice Agent’s `settings.instructions.markdown`.


# Safe Edit Workflow

Recommended workflow:

```text
1. Identify the ai_voice_snippet_id.
2. Understand what the snippet is currently used for.
3. Identify which agents reference the snippet, if possible.
4. Determine the exact change needed.
5. Edit only the intended field or fields.
6. If editing content, preserve useful existing logic unless intentionally replacing it.
7. Validate Handlebars syntax.
8. Confirm the snippet does not reference snippets.*.
9. Review affected AI Voice Agents if the snippet is widely used.
10. Test important agents after the change.
```

For high-risk policy changes:

```text
Disable snippet or affected agents → edit content → review/test → re-enable intentionally
```

---

# `name`

The `name` is the key used inside the `snippets` object.

Example:

```text
card_guidelines
```

Usage in main AI Voice Agent instructions:

```handlebars
{{snippets.card_guidelines}}
```

Changing the snippet name is high impact because existing AI Voice Agent instructions may still reference the old name.

---

## 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
```

Not allowed:

```text
card-guidelines
card guidelines
card.guidelines
_card_guidelines
card_guidelines_
card123
a
```

---

## High-Risk Name Edit

If changing `name`, remember that main AI Voice Agent instructions reference snippets by name.

Old name:

```handlebars
{{snippets.card_guidelines}}
```

New name:

```text
payment_card_guidelines
```

Updated usage required:

```handlebars
{{snippets.payment_card_guidelines}}
```

If agents still reference the old name, the snippet may not render as expected.

Best practice:

```text
Avoid renaming snippets unless necessary.
```

If renaming is necessary, update all AI Voice 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
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "description": "Reusable card collection rules for payment recovery AI Voice Agents that have AddCardToCustomer enabled."
}
```

Updating the description is usually low risk and useful for documentation.

---

# `enabled`

`enabled` determines whether the snippet is enabled.

The KB explains that the `snippets` object contains compiled content of enabled AI Voice Snippets.

Disabling a snippet may affect AI Voice Agents that reference it.

Example:

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": false
}
```

Use disabling when:

- Snippet content is unsafe or outdated.
- A policy is being reviewed.
- A snippet should not be used temporarily.
- The snippet is being replaced.

Before disabling a widely used snippet, consider whether agents that reference it will lose important instruction content.

---

# `content`

`content` is the reusable instruction content.

It can contain:

- Markdown
- Handlebars
- Conditions
- Custom helper usage
- References to `agent`, `item`, `customer`, and `pre_agent_function`

Example:

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "content": "# Transfer Rules\n- If the caller asks for a human, offer to transfer.\n- Do not argue with the caller."
}
```

---

# Editing Content Safely

When editing `content`, MCP should:

1. Preserve the snippet’s purpose.
2. Avoid turning a focused snippet into a full agent instruction document.
3. Keep Markdown structure clear.
4. Validate Handlebars syntax.
5. Guard optional data with `{{#if ...}}`.
6. Reference pre-agent data as `pre_agent_function.response.*`.
7. Use `{{{toString ...}}}` for objects and arrays.
8. Avoid referencing `snippets.*` inside the snippet.
9. Avoid adding system-action instructions unless appropriate for all agents using the snippet.
10. Consider reviewing affected AI Voice Agents.

---

# Snippet Content Compiles With Handlebars

AI Voice Snippets compile like AI Voice Agent instructions.

They use the same Handlebars data the main agent instructions receive when compiling, except 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 another snippet from inside snippet content.

Wrong inside snippet content:

```handlebars
{{snippets.other_snippet}}
```

Correct in main agent instructions:

```handlebars
{{snippets.card_guidelines}}
```

---

# Correct Pre-Agent Function Access

If a snippet references pre-agent Function output, use:

```handlebars
{{pre_agent_function.response.field_name}}
```

Example:

```handlebars
{{#if pre_agent_function.response.company_name}}
- Identify as {{pre_agent_function.response.company_name}} customer support.
{{else}}
- Identify as customer support.
{{/if}}
```

Wrong:

```handlebars
{{company_name}}
```

Wrong:

```handlebars
{{pre_agent_function.company_name}}
```

Correct:

```handlebars
{{pre_agent_function.response.company_name}}
```

For arrays or objects:

```handlebars
{{{toString pre_agent_function.response.product_list}}}
```

---

# Examples

## Rename Only

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "card_guidelines"
}
```

High-impact warning:

```text
Make sure all agent instructions reference the new name.
```

---

## Disable Snippet

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": false
}
```

---

## Enable Snippet

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "enabled": true
}
```

---

## Update Description Only

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "description": "Reusable refund policy rules for inbound support agents. Assumes refund actions are either disabled or controlled by the main agent instructions."
}
```

---

## Update Card Guidelines Content

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "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."
}
```

---

## Update Brand Voice Content

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "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}}"
}
```

---

# MCP Questions Before Editing

Before calling `EditAIVoiceSnippet`, MCP should ask or determine:

1. Which snippet should be edited?
2. What is the `ai_voice_snippet_id`?
3. Which field needs to change: name, description, enabled, or content?
4. Is the snippet used by multiple AI Voice Agents, preferably enough agents to justify shared maintenance?
5. Will this edit change customer-facing behavior?
6. Does the content edit affect payment, refund, subscription, transfer, or compliance rules?
7. Does the snippet reference system actions?
8. Are those system actions enabled in the agents that use the snippet?
9. Does the snippet use Handlebars?
10. Is the Handlebars syntax valid?
11. Does the snippet reference `pre_agent_function.response.*` correctly?
12. Does the snippet avoid referencing `snippets.*` inside its own content?
13. Should the snippet or affected agents be disabled during review?
14. Would editing the AI Voice Agent instructions directly be safer or clearer?
15. Should affected AI Voice Agents be tested after the edit?

---

# Validation Checklist

Before submitting `EditAIVoiceSnippet`:

1. `ai_voice_snippet_id` is present and is 20 characters.
2. Only fields being modified are included.
3. No unknown fields are included.
4. If `name` is included, it follows all naming rules.
5. If `name` is changed, affected agent instructions are reviewed for old references.
6. If `description` is included, it accurately explains usage.
7. If `enabled` is included, enable/disable impact is understood.
8. If `content` is included, it is valid Markdown/Handlebars instruction content.
9. If `content` is included, it remains focused and reusable.
10. If `content` uses customer/item/pre-agent data, optional values are guarded.
11. If `content` uses pre-agent output, it references `pre_agent_function.response.*`.
12. If `content` embeds objects/arrays, it uses `{{{toString ...}}}`.
13. If `content` is included, it does not reference `snippets.*`.
14. If the snippet references system actions, those assumptions are documented.
15. If widely used, affected AI Voice Agents are reviewed or tested.
16. Direct AI Voice Agent instruction editing was considered, especially if fewer than 5 agents are affected.

---

# Common Mistakes

## Mistake: Editing a Shared Policy Without Reviewing Agents

A snippet may be used by many agents.

Changing it can change many customer-facing call flows.

---

## Mistake: Renaming Without Updating Agent Instructions

Wrong:

```text
Rename card_guidelines to payment_card_guidelines
```

but leave agents using:

```handlebars
{{snippets.card_guidelines}}
```

Correct:

```handlebars
{{snippets.payment_card_guidelines}}
```

---

## Mistake: Referencing `snippets` Inside a Snippet

Wrong inside snippet content:

```handlebars
{{snippets.refund_policy}}
```

The `snippets` object is only available in the main agent instructions.

---

## Mistake: Forgetting `response` in Pre-Agent Data

Wrong:

```handlebars
{{pre_agent_function.company_name}}
```

Correct:

```handlebars
{{pre_agent_function.response.company_name}}
```

---

## Mistake: Adding System Action Instructions to a General Snippet

Wrong for a general reusable snippet:

```markdown
- Refund the customer if they ask.
```

Better:

```markdown
- If refund actions are enabled and the main agent instructions allow it, follow the approved refund workflow.
- If refund actions are not enabled, explain that the request must be reviewed by support.
```

---

# 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 edited by the operation. |
| `result` | Human-readable result message. |

---

# Quick Reference

Minimum edit request:

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

Content-only edit:

```json
{
  "ai_voice_snippet_id": "XXXXXXXXXXXXXXXXXXXX",
  "content": "# Transfer Rules\n- If the caller asks for a human, offer to transfer."
}
```

Most important rules:

```text
EditAIVoiceSnippet is a partial update operation.
Only include fields being modified.
Changing a snippet can affect every AI Voice Agent that references it.
Changing a snippet name requires updating agent instruction references.
Snippet content can use Handlebars.
Use pre_agent_function.response.* for pre-agent data.
Do not reference snippets.* inside snippet content.
Snippets do not enable system actions.
Review affected agents after high-impact snippet edits.
Prefer direct AI Voice Agent instruction edits when fewer than 5 agents are affected or the change is agent-specific.
```


---
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.