# RevCent MCP Operation: `EditAIAssistant`

This document describes the `EditAIAssistant` MCP operation and explains how to safely edit AI Assistant triggers, settings, and flows.

Sources used:
- RevCent MCP operation schema for `EditAIAssistant`
- RevCent Knowledge Base: AI Assistants — `https://kb.revcent.com/tools/ai/assistants`
- RevCent AI Assistant Overview — `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md`

---

---

# Read the AI Assistant Overview First

Before creating, editing, or deeply configuring AI Assistants, MCP/AI should read the AI Assistant overview:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md
```

The overview explains AI Assistants as a whole, including:

```text
What AI Assistants are.
Why ecommerce businesses use AI Assistants.
How AI Threads work.
Trigger types.
Thread Builder concepts.
System tools.
Cost controls.
Event filters.
Flow design patterns.
Automation use cases.
Best practices and caveats.
```

This operation file is focused on the specific API/MCP operation. The overview provides the broader conceptual context MCP/AI should understand before making design decisions about an AI Assistant.

## Operation Summary

`EditAIAssistant` edits a previously created RevCent AI Assistant using its 20-character `ai_assistant_id`.

Use this operation to update:

- Name
- Description
- Enabled status
- AI provider integration
- Assistant instructions
- Token limits
- Trigger settings
- Account event settings
- Schedule settings
- Flow / Thread Builder nodes

Important edit behavior:

- `ai_assistant_id` is required.
- Only include properties you want to modify.
- Omitted top-level properties remain unchanged.
- When editing nested objects such as `settings`, provide enough nested structure to avoid unintentionally changing or omitting important configuration.
- When editing `settings.flow`, treat the flow as a complete node graph and preserve all required nodes, IDs, inputs, outputs, and node settings.

---

## Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `ai_assistant_id` | string | Yes | 20-character AI Assistant ID to edit. |

Minimal request:

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

---

## Optional Top-Level Fields

| Field | Type | Description |
|---|---:|---|
| `name` | string | Update the AI Assistant name. |
| `description` | string | Update the human-readable description. |
| `enabled` | boolean | Enable or disable the AI Assistant. |
| `third_party_integration` | string | Update the 20-character AI integration ID powering the assistant. |
| `settings` | object | Update assistant instructions, limits, trigger settings, and/or flow. |

---

# Safe Editing Workflow

Recommended workflow before editing:

1. Retrieve the existing AI Assistant with `GetAIAssistant`.
2. Identify the fields you want to change.
3. If editing the flow, copy the current flow and modify it carefully.
4. Validate that every node connection still points to an existing node.
5. Disable the assistant while making risky trigger or flow changes.
6. Apply the edit.
7. Test with realistic events or on-demand runs.
8. Re-enable after validation.

---

# Simple Edits

## Rename the Assistant

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "name": "Declined Sale - Recovery Analysis v2"
}
```

## Update Description

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "description": "Analyzes declined sales, creates a note, and sends recovery follow-up when appropriate."
}
```

Descriptions are highly recommended because they help humans and other AI Assistants understand what the assistant does.

## Disable Assistant

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

Recommended before major flow or trigger edits.

## Enable Assistant

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

Enable only after testing.

---

# `third_party_integration`

**Type:** `string`  
**Required:** No  
**Length:** 20 characters

The AI third-party integration that powers the assistant.

Supported AI providers include:

- OpenAI
- Google Gemini
- xAI
- OpenRouter

Example:

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "third_party_integration": "YYYYYYYYYYYYYYYYYYYY"
}
```

Important:

- The third-party integration should already exist in RevCent.
- It should be a site integration of type `ai`.
- Changing the AI provider/model can change assistant behavior, output style, latency, and cost.

---

# `settings`

`settings` can update:

- `assistant_instructions`
- `assistant_limits`
- `trigger_settings`
- `flow`

When editing settings, be careful with nested object updates. If you need to preserve existing nested settings, retrieve the assistant first and include the current values you want to keep.

---

## `settings.assistant_instructions`

Base system instructions provided to the AI model for every AI Thread.

Use this for overall behavior.

Do:

```text
You are an AI Assistant that analyzes declined ecommerce sales and determines whether a recovery action is appropriate.
```

Do not:

```text
Void the sale, send an email, and create a note.
```

Specific actions should usually be in `action_step` nodes, not assistant instructions.

Example edit:

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "assistant_instructions": "You are an AI Assistant that reviews declined ecommerce sales and identifies recovery opportunities."
  }
}
```

---

## `settings.assistant_limits`

Token limits help control usage and cost.

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "assistant_limits": {
      "thread_max_tokens": 100000,
      "token_max_per_day": 500000
    }
  }
}
```

### `thread_max_tokens`

Maximum tokens one AI Thread can consume.

- `0` means no limit.
- Use to prevent runaway threads.

### `token_max_per_day`

Maximum tokens the assistant can consume in a 24-hour period.

- `0` means no limit.
- Strongly recommended for budget control.

---

# Trigger Settings

`settings.trigger_settings` determines what activates the assistant.

Supported trigger values:

```text
account_event
on_demand
schedule
```

| Trigger | Description |
|---|---|
| `account_event` | Runs when a specific RevCent account event occurs. |
| `on_demand` | Runs via API, web app, or as a system tool from another AI Assistant. |
| `schedule` | Runs on a fixed schedule using a five-part cron expression. |

---

# Editing Trigger: `account_event`

Use `account_event` when the assistant should run automatically after a RevCent event.

Example edit:

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "account_event",
      "account_event": {
        "notation": "sale.created.failed.declined",
        "delay": {
          "time_value": 5,
          "time_unit": "minutes"
        },
        "limits": {
          "max_run_count": 1
        }
      }
    }
  }
}
```

---

## Account Event Notation

The notation determines the event.

Examples:

```text
sale.created.failed.declined
sale.created.success.paid
chargeback.created
customer.created
shipping.updated.shipped
subscription_renewal.updated.failed
trial.updated.expired.success
```

Best practices:

- Use the most specific notation possible.
- Avoid broad notations unless the assistant can safely handle every subtype.
- Review filters and flow steps after changing notation.
- The first word in the notation determines item type and available status filters.

---

## Event Item Type

The first segment of the account event notation determines item type.

| Notation | Item Type |
|---|---|
| `sale.created.failed.declined` | `sale` |
| `customer.created` | `customer` |
| `shipping.updated.shipped` | `shipping` |
| `subscription_renewal.updated.failed` | `subscription_renewal` |
| `trial.updated.expired.success` | `trial` |

If you change the notation from one item type to another, review all flow steps because the AI’s starting context changes.

---

## Account Event Filters

Filters restrict whether the assistant should run.

### Campaign Filter

```json
"filters": {
  "campaign_filter": ["XXXXXXXXXXXXXXXXXXXX"]
}
```

Use when only specific campaigns should trigger the assistant.

### Status Filter

```json
"filters": {
  "status_filter": ["declined"]
}
```

Available statuses depend on the item type.

### Metadata Filter

```json
"filters": {
  "metadata_filter": [
    {
      "name": "source",
      "value": "affiliate"
    }
  ]
}
```

All metadata name/value pairs must match.

---

## Filter Function

A filter function can further decide whether the assistant should run.

```json
"filter_function": "XXXXXXXXXXXXXXXXXXXX"
```

Requirements:

- Function must have `event_source: "api_direct"`.
- Function receives item data.
- Function returns only:
  - `"pass"`
  - `"fail"`

Pass:

```javascript
callback(null, "pass");
```

Fail:

```javascript
callback(null, "fail");
```

To remove a filter function in `EditAIAssistant`, submit an empty string:

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "account_event",
      "account_event": {
        "filter_function": ""
      }
    }
  }
}
```

---

## Delay

Delay controls how long after the account event the assistant starts.

```json
"delay": {
  "time_value": 10,
  "time_unit": "minutes"
}
```

Allowed units:

```text
minutes
hours
days
```

KB notes:

- Default minimum is 1 minute.
- Maximum is 30 days.
- Delays are useful when related events may occur shortly after the first event.

---

## Limits

Limits prevent accidental repeat runs for the same item.

```json
"limits": {
  "max_run_count": 1
}
```

Strongly recommended:

```text
max_run_count = 1
```

Use `min_time_value` and `min_time_unit` only when allowing multiple runs per item.

```json
"limits": {
  "max_run_count": 2,
  "min_time_value": 1,
  "min_time_unit": "days"
}
```

---

# Editing Trigger: `on_demand`

Use `on_demand` when the assistant should run only when explicitly triggered.

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "on_demand"
    }
  }
}
```

On-demand assistants can run from:

- API
- RevCent web app
- Another AI Assistant as a system tool

Use cases:

- Manual customer review.
- Support-triggered analysis.
- A parent assistant triggers a specialized child assistant.
- API-driven customer or sale summaries.

---

# Editing Trigger: `schedule`

Use `schedule` when the assistant should run on a fixed cron schedule.

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "schedule",
      "schedule": {
        "cron_expression": "0 9 * * *",
        "cron_timezone": "America/New_York"
      }
    }
  }
}
```

## `cron_expression`

Must be a standard five-part cron expression:

```text
minute hour day-of-month month day-of-week
```

Example:

```text
0 9 * * *
```

Meaning: every day at 9:00 AM in the configured timezone.

Important KB notes:

- Intervals cannot be less than 1 hour apart.
- Scheduled assistants are checked every 10 minutes, so exact execution may vary by up to 10 minutes.
- Only standard five-part cron expressions are supported.
- `@daily`, `@hourly`, and similar shortcut syntax is not supported.

## `cron_timezone`

Must be a valid IANA timezone string.

Examples:

```text
UTC
America/New_York
America/Los_Angeles
Europe/London
```

If omitted, UTC is used.

---

# Editing Flow / Thread Builder

The `settings.flow` array defines how the assistant thread runs.

When editing flow, treat it as the full graph of the assistant.

Important:

- Retrieve the current assistant first.
- Copy the current flow.
- Modify the copied flow.
- Preserve node IDs unless intentionally changing them.
- Update all connections if any node ID changes.
- Ensure the graph starts at `start_thread`.
- Ensure the graph can safely end.
- Test before enabling.

---

## Flow Node Types

Supported node types:

```text
start_thread
action_step
action_branch
action_time_delay
action_end_thread
```

| Node Type | Purpose |
|---|---|
| `start_thread` | Starting point of the AI Thread. |
| `action_step` | Sends a task/message to the AI. |
| `action_branch` | AI chooses a path based on condition messages. |
| `action_time_delay` | Pauses the thread before continuing. |
| `action_end_thread` | Ends the thread. |

---

## Flow Connection Rules

- Every node must have a unique `id`.
- `start_thread` has no inputs.
- `action_end_thread` has no outputs.
- A node input can connect from only one other node output.
- A node output can connect to only one other node input.
- Multiple nodes cannot connect to the same input.
- Multiple nodes cannot connect from the same output.
- `action_branch` can use `output_1`, `output_2`, `output_3`, and fallback `output_4`.

---

## Editing an `action_step`

Use `action_step` to change specific AI instructions.

Example edit to replace the full flow with updated step message:

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "flow": [
      {
        "id": "start",
        "type": "start_thread",
        "outputs": {
          "output_1": {
            "connections": [
              {
                "node": "step_review",
                "input": "input_1"
              }
            ]
          }
        }
      },
      {
        "id": "step_review",
        "type": "action_step",
        "inputs": {
          "input_1": {
            "connections": [
              {
                "node": "start",
                "input": "output_1"
              }
            ]
          }
        },
        "outputs": {
          "output_1": {
            "connections": [
              {
                "node": "end",
                "input": "input_1"
              }
            ]
          }
        },
        "node_settings": {
          "step_message": "Review the triggered item and create a concise note summarizing the most important details."
        }
      },
      {
        "id": "end",
        "type": "action_end_thread",
        "inputs": {
          "input_1": {
            "connections": [
              {
                "node": "step_review",
                "input": "output_1"
              }
            ]
          }
        }
      }
    ]
  }
}
```

---

## Editing an `action_branch`

An `action_branch` lets the AI decide which path to take.

It behaves like:

```text
if output_1_message is true
else if output_2_message is true
else if output_3_message is true
else output_4
```

Required:

```json
"output_1_message"
```

Optional:

```json
"output_2_message"
"output_3_message"
```

Important:

- Output 4 is fallback / else.
- The AI chooses only one branch.
- Keep branch condition messages clear and mutually distinguishable where possible.

Example conditions:

```json
"node_settings": {
  "output_1_message": "The customer purchased a USB.",
  "output_2_message": "The customer purchased a laptop.",
  "output_3_message": "The customer did not purchase a laptop or USB."
}
```

---

## Editing an `action_time_delay`

Use `action_time_delay` when the thread should wait before continuing.

```json
"node_settings": {
  "time_unit": "hours",
  "time_value": "2"
}
```

Allowed units:

```text
minutes
hours
days
```

Important KB notes:

- Minimum delay is 1 minute.
- Maximum delay is 3 days.
- Threads are stored for a maximum of 7 days since created.

---

## Editing an `action_end_thread`

Use `action_end_thread` to explicitly end the thread.

Important:

- No outputs.
- Useful for clear branch endings.
- If a node has no additional node to continue to, the thread self-ends.

---

## Flow Positioning

`position` is optional and only affects UI layout.

```json
"position": {
  "x_axis": 400,
  "y_axis": 0
}
```

Recommended:

- Provide positions for readability.
- UI nodes are approximately 300px wide and 400px high.
- Keep branches spaced vertically.

---

# Safe Flow Editing Checklist

Before submitting a new `settings.flow`:

1. Confirm there is exactly one intended `start_thread`.
2. Confirm each node ID is unique.
3. Confirm every connection references an existing node.
4. Confirm every connection references valid input/output names.
5. Confirm `start_thread` has no inputs.
6. Confirm `action_end_thread` has no outputs.
7. Confirm `action_step` nodes have `step_message`.
8. Confirm `action_branch` nodes have at least `output_1_message`.
9. Confirm `action_time_delay` nodes have `time_unit` and `time_value`.
10. Confirm no input has more than one incoming connection.
11. Confirm no output has more than one outgoing connection.
12. Confirm branch fallback paths are safe.
13. Confirm no required path is accidentally disconnected.
14. Disable the assistant before major flow edits.
15. Test after editing.

---

# Common Edit Examples

## Update Assistant Instructions Only

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "assistant_instructions": "You are an AI Assistant that reviews failed ecommerce payments and identifies likely recovery opportunities."
  }
}
```

## Update Token Limits Only

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "assistant_limits": {
      "thread_max_tokens": 100000,
      "token_max_per_day": 500000
    }
  }
}
```

## Change to On Demand

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "on_demand"
    }
  }
}
```

## Change to Schedule

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "schedule",
      "schedule": {
        "cron_expression": "0 9 * * *",
        "cron_timezone": "America/New_York"
      }
    }
  }
}
```

## Change Account Event Notation

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "account_event",
      "account_event": {
        "notation": "subscription_renewal.updated.failed",
        "limits": {
          "max_run_count": 1
        }
      }
    }
  }
}
```

## Remove Filter Function

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "account_event",
      "account_event": {
        "filter_function": ""
      }
    }
  }
}
```

---

# Output Schema

A successful `EditAIAssistant` response returns:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1740000000,
  "code": 1,
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "result": "..."
}
```

Fields:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | Response code. `1` indicates success. |
| `ai_assistant_id` | 20-character ID of the edited AI Assistant. |
| `result` | Human-readable result message. |

---

# Implementation Checklist

Before calling `EditAIAssistant`:

0. Confirm the AI Assistant overview has been reviewed when making broader design decisions.
1. Confirm the `ai_assistant_id`.
2. Retrieve the current assistant if editing settings or flow.
3. Include only properties you intend to modify.
4. Disable the assistant before major trigger or flow changes.
5. Use broad behavior in `assistant_instructions`.
6. Put specific tasks in flow `action_step` nodes.
7. Set token limits to control cost.
8. For account-event triggers, use the most specific notation possible.
9. For account-event triggers, keep `max_run_count` set to `1` unless repeated runs are intentional.
10. Use a filter function only when simple filters are not enough.
11. Remove a filter function by sending an empty string.
12. For schedule triggers, use a valid five-part cron expression.
13. For flow edits, validate every node and connection.
14. Preserve node IDs unless intentionally changing them.
15. Test with realistic events or on-demand runs.
16. Re-enable only after validation.

---

# Quick Reference

Required field:

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

Disable before editing:

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

Update description:

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "description": "Analyzes declined sales and creates recovery guidance."
}
```

Remove account-event filter function:

```json
{
  "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "trigger_settings": {
      "trigger": "account_event",
      "account_event": {
        "filter_function": ""
      }
    }
  }
}
```


---

# Overview Reference

MCP/AI should read the AI Assistant overview for broad conceptual understanding:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md
```


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