# RevCent MCP Operation: `TriggerAIAssistant` This document explains how MCP/AI clients should use the `TriggerAIAssistant` operation in RevCent. `TriggerAIAssistant` triggers a specific AI Assistant using its AI Assistant ID. Triggering an AI Assistant creates a new AI Thread that runs autonomously. Before using this operation, 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 trigger types, AI Threads, Thread Builder behavior, system tools, usage limits, ecommerce use cases, and reporting concepts. Sources: - RevCent MCP/API schema for `TriggerAIAssistant` - RevCent AI Assistant overview: `https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md` --- ## Operation Summary `TriggerAIAssistant` starts an AI Assistant manually/API-directly. Important: ```text Only AI Assistants with trigger type `on_demand` can be triggered through the API/MCP. ``` When triggered, RevCent creates an AI Thread: ```text TriggerAIAssistant ↓ RevCent creates a new AI Thread ↓ The AI Assistant runs autonomously according to its Thread Builder flow ↓ The response returns the new ai_thread_id ``` This operation should be used intentionally. Triggering an AI Assistant is not just retrieving data; it starts automation that may analyze data, call system actions, create notes, insert metadata, send emails, trigger Functions, create AI Memos, trigger other assistants, or perform other configured work. --- # Read the AI Assistant Overview First MCP/AI should read the broader AI Assistant overview before triggering assistants for anything beyond a simple explicit user request: ```text https://revcent.com/documentation/markdown/mcp/operation/OverviewAIAssistant.md ``` The overview provides necessary context about: ```text What AI Assistants are. How AI Threads work. Event, schedule, and on-demand triggers. Thread Builder flow. System tools. AI Memos. Functions. Email Templates. BigQuery usage. Cost controls. Usage limits. Filtering concepts. Best practices. Caveats. ``` This operation guide explains how to trigger an assistant. The overview explains why, when, and how AI Assistants should be designed and used. --- # Important On-Demand Trigger Caution `TriggerAIAssistant` can only trigger assistants configured with an `on_demand` trigger. This matters because on-demand triggering is different from event triggering. Event-triggered assistants may use event filters such as: ```text Campaign filters. Status filters. Metadata filters. Filter Functions. Max Runs Per Item. Min Run Interval. Event delay logic. ``` On-demand API/MCP triggering does not evaluate those event-trigger eligibility controls. Filters and filter Functions do not apply to `TriggerAIAssistant`. Therefore: ```text Do not trigger an AI Assistant casually. Do not trigger an AI Assistant just because one exists. Do not trigger an AI Assistant based on MCP/AI self-judgment alone unless the workflow explicitly calls for it. Do not use TriggerAIAssistant as a generic reasoning tool when the assistant has a specific operational purpose. ``` Triggering should have a specific purpose. Good reasons to trigger an AI Assistant: ```text The user explicitly asks MCP/AI to trigger a specific AI Assistant. A documented external workflow says to trigger this assistant when X occurs. Another AI Assistant is intentionally handing off to a specific on-demand assistant. A support/admin workflow intentionally exposes this assistant for a specific item type. A Function or external automation has clear rules for when to trigger this assistant. ``` Poor reasons to trigger an AI Assistant: ```text The MCP is unsure what to do and randomly triggers an assistant. The MCP wants the assistant to make a decision that the MCP could make directly. The user did not request it and no workflow says to trigger it. The assistant's purpose is unclear. The assistant may perform actions that affect customers, payments, refunds, emails, notes, or metadata without explicit intent. ``` --- --- # Filters and Filter Functions Do NOT Apply to TriggerAIAssistant This is a critical distinction. `TriggerAIAssistant` can only trigger an AI Assistant configured with trigger type: ```text on_demand ``` The `on_demand` trigger type has no event filters. That means the following do **not** apply when using `TriggerAIAssistant`: ```text Campaign filters Status filters Metadata filters Event delay filtering Filter Functions Event-trigger eligibility checks ``` In other words: ```text Filters and filter functions DO NOT apply to triggering an AI Assistant with TriggerAIAssistant. ``` This operation is dependent on intentional use. MCP/AI must not assume that a filter function or configured event filter will prevent an inappropriate on-demand trigger. If `TriggerAIAssistant` is called successfully, the AI Assistant will create a new AI Thread and begin running according to its configured Thread Builder flow. Therefore, before calling `TriggerAIAssistant`, MCP/AI must determine that the trigger is appropriate. Appropriate reasons include: ```text The user explicitly asked to trigger the AI Assistant. A documented external workflow specifically says to trigger this AI Assistant for this reason. Another AI Assistant is intentionally handing off to this AI Assistant. A Function or automation rule has already determined that the assistant should run. A human/admin support workflow intentionally triggered the assistant. ``` Inappropriate reasons include: ```text The MCP thinks the assistant might be useful. The MCP is unsure what to do next. The MCP expects event filters to block an ineligible run. The MCP expects a filter Function to decide whether the assistant should run. The assistant may perform consequential actions and no user/workflow explicitly requested it. ``` If eligibility logic is needed before calling an on-demand AI Assistant, that logic must happen before `TriggerAIAssistant` is called. Examples: ```text External workflow checks eligibility, then calls TriggerAIAssistant only if eligible. Function checks custom conditions, then calls TriggerAIAssistant only if eligible. MCP confirms the user specifically requested the assistant trigger, then calls TriggerAIAssistant. ``` Do not rely on AI Assistant filters for on-demand/API triggering because there are no on-demand trigger filters. # Recommended Trigger Standard Before triggering an AI Assistant, MCP/AI should confirm the trigger meets this standard: ```text There is a specific AI Assistant ID. The assistant is configured for on_demand triggering, and MCP/AI understands that no filters or filter Functions apply to this trigger. The assistant's purpose is understood. The user explicitly requested the trigger, or an external workflow explicitly instructs triggering under known conditions. The assistant may run autonomously after triggering. The user or workflow understands that a new AI Thread will be created. ``` If the assistant is item-specific, MCP/AI should also confirm: ```text The target item type is known. The target item ID is known. The assistant is designed to handle that item type. ``` If the assistant is not item-specific, MCP/AI should not invent item context. --- # Schema Overview `TriggerAIAssistant` input schema: | Field | Type | Required | Description | |---|---:|---:|---| | `ai_assistant_id` | string | Yes | 20-character AI Assistant ID. | | `source_type` | enum string | No | Only provide when triggering the assistant for a specific RevCent item. Currently `item`. | | `item_type` | enum string | No | Only provide when `source_type = item`. Specifies the RevCent item type. | | `item_id` | string | No | Only provide when `source_type = item`. 20-character ID of the item matching `item_type`. | | `previous_ai_thread` | object | No | Optional object for passing an existing AI Thread into the new assistant trigger. | | `messages` | array | No | Optional new messages to include when triggering the assistant. | The schema has: ```json "additionalProperties": false ``` Do not send unknown fields. --- # Required Field: `ai_assistant_id` `ai_assistant_id` is the only required field. Example minimum request: ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX" } ``` This is valid when the assistant does not need a specific RevCent item and can run as a general on-demand task. Examples of non-item-specific assistants: ```text Daily revenue summary assistant. General BigQuery analysis assistant. Operations summary assistant. Gateway health review assistant. Support backlog analysis assistant. Scheduled-style analysis triggered manually. Assistant that runs based only on the provided messages. Assistant that performs a general task not tied to one item. ``` If the user knows the assistant name but not the ID, MCP/AI should use: ```text GetAIAssistants ``` to find the correct assistant ID. Do not guess AI Assistant IDs. --- # Item Context Is Optional `source_type`, `item_type`, and `item_id` are not always required. They should be provided only when the assistant is meant to run against a specific RevCent item. Some AI Assistants are item-specific. Examples: ```text Analyze this sale. Summarize this customer. Review this chargeback. Inspect this shipment issue. Analyze this failed subscription renewal. ``` Those should include: ```text source_type = item item_type = the relevant item type item_id = the relevant item ID ``` Other AI Assistants are task-based and not tied to a single item. Examples: ```text Run a daily revenue analysis. Summarize support trends. Review gateway performance. Run a BigQuery report. Analyze refund trends. Create an operations memo. Trigger a general workflow. ``` Those may require only: ```text ai_assistant_id ``` and optionally: ```text messages ``` MCP/AI should not force item context when the assistant is not item-specific. --- # Item Context Fields Use item context when the assistant should run against a specific RevCent item. Fields: ```text source_type item_type item_id ``` Example: ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "source_type": "item", "item_type": "sale", "item_id": "YYYYYYYYYYYYYYYYYYYY" } ``` This tells the assistant: ```text Run this on-demand assistant with this specific item as context. ``` --- ## `source_type` Currently supported value: ```text item ``` Only provide `source_type` if the assistant is being triggered for a specific RevCent item. Do not include `source_type` for a generic assistant trigger that does not need item context. --- ## `item_type` Only provide `item_type` when: ```text source_type = item ``` Supported values: ```text sale customer product_sale shipping subscription subscription_renewal salvage_transaction transaction chargeback fraud_detection ``` Examples: | User/Workflow Goal | item_type | |---|---| | Analyze a sale | `sale` | | Summarize a customer | `customer` | | Review one product sale | `product_sale` | | Analyze a shipment issue | `shipping` | | Review subscription status | `subscription` | | Analyze failed renewal | `subscription_renewal` | | Review salvage/recovery opportunity | `salvage_transaction` | | Analyze a transaction | `transaction` | | Review chargeback risk | `chargeback` | | Analyze fraud detection | `fraud_detection` | --- ## `item_id` `item_id` is the 20-character ID of the item corresponding to `item_type`. Example: ```json { "source_type": "item", "item_type": "customer", "item_id": "YYYYYYYYYYYYYYYYYYYY" } ``` MCP/AI should not guess item IDs. If the item ID is unknown and the assistant is item-specific, retrieve or search for the item first. If the assistant is not item-specific, do not provide an arbitrary `item_id`. --- # Optional `messages` `messages` lets MCP/AI provide new messages to the AI Assistant when triggering it. Each message has: | Field | Type | Description | |---|---:|---| | `role` | enum string | `user` or `system`. | | `content` | string | Message content. | Example: ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "messages": [ { "role": "user", "content": "Run a revenue summary for the last 7 days and create an AI Memo if refund rate looks abnormal." } ] } ``` Use messages when the assistant needs an explicit instruction or extra context that is not already supplied by item context. Good message content: ```text Clear. Specific. Limited to the task. Free of secrets or raw payment data. Aligned with the assistant's purpose. ``` Avoid: ```text Long unrelated context. Internal MCP reasoning traces. Conflicting instructions. Duplicating previous thread messages. Telling the assistant to perform actions outside its purpose. ``` --- # Optional `previous_ai_thread` `previous_ai_thread` is used when triggering an AI Assistant and passing an existing AI Thread to it. Schema: ```json { "previous_ai_thread": { "ai_thread_id": "XXXXXXXXXXXXXXXXXXXX", "include_messages": true } } ``` Fields: | Field | Type | Description | |---|---:|---| | `ai_thread_id` | string | 20-character AI Thread ID. | | `include_messages` | boolean | Whether to pass the existing AI Thread's messages into the new trigger. | --- ## `previous_ai_thread` Is Usually Not Needed In most MCP/API triggering workflows, `previous_ai_thread` is not needed. Typical item-specific trigger: ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "source_type": "item", "item_type": "sale", "item_id": "YYYYYYYYYYYYYYYYYYYY" } ``` Typical non-item-specific trigger: ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "messages": [ { "role": "user", "content": "Run the standard operations summary." } ] } ``` Use `previous_ai_thread` only when there is a specific reason to pass context from an existing thread. The most common valid use case is: ```text One AI Assistant is intentionally handing off to another AI Assistant. ``` Example: ```text General Risk Assistant reviews a customer. ↓ It determines a chargeback-specific review is needed. ↓ It triggers a Chargeback Specialist Assistant. ↓ previous_ai_thread passes the original AI Thread context. ``` --- ## When To Use `previous_ai_thread` Use `previous_ai_thread` when: ```text An assistant handoff needs prior thread context. A multi-assistant workflow intentionally chains assistants. The new assistant needs to understand what happened in the previous assistant. The previous thread contains important decisions, analysis, messages, or tool results. The workflow was designed to pass thread context. ``` Examples: ```text Primary support assistant triggers refund specialist assistant. Risk triage assistant triggers fraud review assistant. Declined sale assistant triggers recovery email assistant. Chargeback threat assistant triggers chargeback mitigation assistant. ``` --- ## When NOT To Use `previous_ai_thread` Do not use `previous_ai_thread` when: ```text The assistant can get needed context from the item. The assistant can get needed context from provided messages. The user is triggering a standalone assistant. The previous thread is unrelated. The previous thread would add unnecessary token cost. The old messages may confuse the new assistant. The previous thread contains sensitive or irrelevant context. The MCP is using it just because a previous thread exists. ``` Remember: ```text Passing existing thread messages consumes more tokens. ``` Only pass previous thread context when it is necessary. --- ## `include_messages` `include_messages` controls whether existing AI Thread messages are passed. If `include_messages = true`, the new assistant receives the previous thread's messages. This can be useful for handoffs, but it increases token use. Use `include_messages = true` only when: ```text The prior conversation/history is necessary. The new assistant must understand prior reasoning/results. The assistant handoff was intentionally designed. ``` Use `include_messages = false` or omit `previous_ai_thread` when item/message context is enough. --- ## Do Not Duplicate Previous Thread Messages If providing `previous_ai_thread` and `include_messages = true`, do not also include duplicate previous messages in the `messages` array. Bad: ```json { "previous_ai_thread": { "ai_thread_id": "AAAAAAAAAAAAAAAAAAAA", "include_messages": true }, "messages": [ { "role": "user", "content": "Duplicate of an existing prior thread message." } ] } ``` Better: ```json { "previous_ai_thread": { "ai_thread_id": "AAAAAAAAAAAAAAAAAAAA", "include_messages": true }, "messages": [ { "role": "user", "content": "Continue by performing the chargeback-specific review." } ] } ``` The new message should add only new instruction/context, not duplicate old messages. --- # Output Schema Successful response can include: ```json { "api_call_id": "XXXXXXXXXXXXXXXXXXXX", "api_call_unix": 1740000000, "code": 1, "ai_thread_id": "YYYYYYYYYYYYYYYYYYYY", "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "result": "..." } ``` Important output fields: | Field | Meaning | |---|---| | `api_call_id` | API call ID for the trigger operation. | | `api_call_unix` | Unix timestamp of when the API call was initiated. | | `code` | Response code. `1` means success. | | `ai_thread_id` | Newly created AI Thread ID. | | `ai_assistant_id` | AI Assistant ID that was triggered. | | `result` | Human-readable result message. | The returned `ai_thread_id` is important for later debugging/review. --- # Triggering Creates an Autonomous AI Thread After triggering, the AI Assistant runs according to its configured Thread Builder flow. Depending on the assistant configuration, it may: ```text Retrieve records. Analyze item/customer/sale/subscription data. Run BigQuery. Create notes. Insert metadata. Send email templates. Trigger Functions. Create AI Memos. Trigger other AI Assistants. Branch based on AI reasoning. Wait using Time Delay nodes. End the thread. ``` MCP/AI should not assume the thread completed instantly unless thread status/outputs are retrieved through the appropriate AI Thread/assistant review mechanisms. --- # Explicit User Request Rule MCP/AI should typically trigger an AI Assistant only when the user explicitly requests it. Examples: ```text "Trigger the declined sale assistant for this sale." "Run the customer summary assistant for this customer." "Start the chargeback review assistant on this chargeback." "Use the refund analysis assistant on this transaction." "Run the daily operations assistant now." ``` When the user makes an explicit request, MCP/AI should: ```text Confirm the assistant ID or locate it with GetAIAssistants. Confirm item context if the assistant is item-specific. Do not require item context if the assistant is task-based/non-item-specific. Trigger the assistant. Return the created ai_thread_id. ``` --- # External Workflow Rule Triggering is also appropriate when an external workflow explicitly says to trigger an AI Assistant under specific conditions. Examples: ```text A CRM workflow says: trigger Assistant X when a VIP customer submits a cancellation request. A Function says: trigger Assistant Y if fraud_score > 80. An internal support workflow says: trigger Assistant Z after a customer has more than 3 refund-related notes in 7 days. Another AI Assistant says: trigger the specialized Chargeback Assistant when chargeback risk is detected. ``` The key requirement is: ```text The workflow must specify what should trigger the assistant and why. ``` Avoid vague triggering such as: ```text Trigger some assistant if it might help. ``` --- # Another AI Assistant Triggering This Operation AI Assistants may be able to trigger other AI Assistants as part of a designed workflow. This is one of the main cases where `previous_ai_thread` may be appropriate. Pattern: ```text Assistant A analyzes broad issue. Assistant A determines specialized Assistant B is needed. Assistant A triggers Assistant B. Assistant A passes previous_ai_thread if B needs A's thread context. Assistant B runs specialized workflow. ``` Good handoff design: ```text Assistant B has a narrow specialty. Assistant B description clearly explains when to use it. Assistant A is instructed exactly when to trigger B. previous_ai_thread is only passed when needed. messages add a concise handoff instruction. ``` --- # Triggering Without Item Context Examples ## Trigger a General Revenue Summary Assistant ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "messages": [ { "role": "user", "content": "Run the standard revenue summary for the last 7 days." } ] } ``` ## Trigger an Operations Review Assistant ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "messages": [ { "role": "user", "content": "Review current operations trends and create an AI Memo if urgent issues are found." } ] } ``` ## Trigger With Only the Assistant ID ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX" } ``` This is appropriate only when the assistant's configured Thread Builder does not need item context or extra message context. --- # Triggering With Item Context Examples ## Trigger Assistant for a Sale ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "source_type": "item", "item_type": "sale", "item_id": "YYYYYYYYYYYYYYYYYYYY" } ``` ## Trigger Assistant for a Customer ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "source_type": "item", "item_type": "customer", "item_id": "YYYYYYYYYYYYYYYYYYYY" } ``` ## Trigger Assistant for a Chargeback ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "source_type": "item", "item_type": "chargeback", "item_id": "YYYYYYYYYYYYYYYYYYYY" } ``` ## Trigger Assistant for a Subscription Renewal ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "source_type": "item", "item_type": "subscription_renewal", "item_id": "YYYYYYYYYYYYYYYYYYYY" } ``` --- # Triggering With Messages Use `messages` when the assistant needs additional specific instructions. ```json { "ai_assistant_id": "XXXXXXXXXXXXXXXXXXXX", "source_type": "item", "item_type": "customer", "item_id": "YYYYYYYYYYYYYYYYYYYY", "messages": [ { "role": "user", "content": "Summarize this customer's recent support and payment history. If urgent escalation is needed, create an AI Memo." } ] } ``` The message should be concise and should not override the assistant's intended purpose. --- # Triggering With Previous Thread Handoff Example assistant-to-assistant handoff: ```json { "ai_assistant_id": "BBBBBBBBBBBBBBBBBBBB", "source_type": "item", "item_type": "chargeback", "item_id": "CCCCCCCCCCCCCCCCCCCC", "previous_ai_thread": { "ai_thread_id": "AAAAAAAAAAAAAAAAAAAA", "include_messages": true }, "messages": [ { "role": "user", "content": "Continue from the prior risk triage and perform the chargeback-specific review." } ] } ``` Use this only when the new assistant needs prior thread context. --- # Safety and Business Impact Triggering an AI Assistant may have business impact. Depending on system tools enabled and Thread Builder steps, the assistant may: ```text Send customer emails. Create notes. Insert metadata. Trigger Functions. Create AI Memos. Run BigQuery. Trigger other assistants. Perform customer/account/sale/subscription analysis. Take revenue, refund, support, or risk-related actions if configured. ``` Therefore MCP/AI should check: ```text What is the assistant's name? What is the assistant's description? What is its trigger type? Is it designed to be item-specific or task-based? If item-specific, what item types is it designed for? What system tools/actions does it have? What might it do after starting? Is the user or workflow explicitly requesting this? ``` --- # Cost Considerations Triggering creates an AI Thread and consumes AI resources. Costs may include: ```text Third-party AI model usage. RevCent AI time. Token usage. Tool/API action usage. Longer thread flows. Thread delays and follow-up steps. ``` MCP/AI should avoid unnecessary triggers because each trigger can create cost. For recurring or automated use, ensure usage limits and workflow conditions are appropriate. --- # BigQuery Reporting After Triggering After triggering, activity can often be analyzed through BigQuery. Useful tables include: ```text revcent.user.ai_assistant revcent.user.api_call note metadata on relevant item tables sale transaction subscription_renewal salvage_transaction chargeback ``` The `api_call` table can include: ```text api_call.ai_assistant ``` This allows reports on what AI Assistants did. Examples: ```text How many API actions did this assistant perform? How many actions succeeded or failed? Did it send emails? Did it create notes? Did it insert metadata? Did it trigger Functions? Did it create revenue-related actions? Did assistant-triggered revenue workflows succeed? ``` Use: ```text BigQueryRunQuery ``` for reporting, metrics, analytics, aggregations, and data mining. --- # Common Mistakes ## Mistake: Triggering the Wrong Trigger Type Wrong: ```text Trigger an event-based assistant through API. ``` Correct: ```text Only assistants with trigger type on_demand can be triggered through TriggerAIAssistant. ``` ## Mistake: Expecting Filters or Filter Functions to Apply Wrong: ```text Call TriggerAIAssistant and assume campaign/status/metadata filters or a filter Function will decide whether it should run. ``` Correct: ```text Do all eligibility checks before calling TriggerAIAssistant. The on_demand trigger type has no filters, and filter Functions do not apply. ``` ## Mistake: Triggering Without a Purpose Wrong: ```text Trigger an assistant because it might be useful. ``` Correct: ```text Trigger only when the user explicitly asks or a workflow specifically says to trigger that assistant for a known reason. ``` ## Mistake: Assuming Event Filters Apply Wrong: ```text Assume campaign/status/metadata/filter-function eligibility checks from event triggers will protect an on-demand trigger. ``` Correct: ```text Only trigger on-demand assistants when the workflow already determined the item/task is eligible. ``` ## Mistake: Requiring Item Context When the Assistant Is Not Item-Specific Wrong: ```text Force source_type, item_type, and item_id for a general report assistant. ``` Correct: ```text Use only ai_assistant_id and optional messages when the assistant is task-based and not tied to one item. ``` ## Mistake: Passing Previous Thread Context by Default Wrong: ```text Always pass previous_ai_thread if one exists. ``` Correct: ```text Pass previous_ai_thread only when handing off from one assistant to another or when prior thread context is necessary. ``` ## Mistake: Duplicating Messages Wrong: ```text Pass previous_ai_thread.include_messages = true and also duplicate all prior messages in messages. ``` Correct: ```text Use previous_ai_thread for prior context and use messages only for new concise instructions. ``` ## Mistake: Missing Item Context for an Item-Specific Assistant Wrong: ```text Trigger a sale analysis assistant without source_type, item_type, or item_id. ``` Correct: ```text Provide source_type = item, item_type = sale, and the 20-character sale item_id. ``` --- # MCP/AI Decision Guide Use `TriggerAIAssistant` when: ```text The assistant is on_demand, and MCP/AI understands that on_demand triggers have no filters or filter Functions. The user explicitly requested the assistant trigger. An external workflow explicitly requires this assistant to be triggered. Another assistant is intentionally handing off to this assistant. The assistant ID is known or can be found. The item context is known if the assistant is item-specific. No item context is supplied if the assistant is task-based and not tied to one RevCent item. ``` Do not use `TriggerAIAssistant` when: ```text The assistant is not on_demand. The purpose is vague. The user did not ask and no workflow explicitly says to trigger it. The MCP/AI is self-judging that an assistant might be useful without a defined rule. The assistant may perform consequential actions and the user/workflow has not requested it. The assistant's required context is unknown. ``` --- # Validation Checklist Before calling `TriggerAIAssistant`: 1. `ai_assistant_id` is known. 2. `ai_assistant_id` is 20 characters. 3. The assistant is configured with trigger type `on_demand`. 4. The assistant's purpose is understood. 5. The trigger is explicitly requested by the user or required by a specific workflow rule. 6. No filters or filter Functions are expected to run; all eligibility checks were completed before calling `TriggerAIAssistant`. 7. If the assistant is item-specific, `source_type = item`, `item_type`, and `item_id` are provided. 8. If the assistant is not item-specific, item context is not forced or invented. 9. If messages are provided, they are concise, relevant, and aligned with the assistant purpose. 10. `previous_ai_thread` is omitted unless thread handoff/context transfer is actually needed. 11. If `previous_ai_thread.include_messages = true`, duplicate old messages are not included in `messages`. 12. The assistant's potential system actions are appropriate for the trigger. 13. Cost and usage implications are acceptable. 14. The created `ai_thread_id` will be captured for follow-up/debugging. --- # Key Takeaways ```text TriggerAIAssistant creates a new autonomous AI Thread for a specific AI Assistant. ``` ```text Only AI Assistants configured as on_demand can be triggered through API/MCP. ``` ```text Only ai_assistant_id is required. ``` ```text source_type, item_type, and item_id are optional and should only be used when the assistant is meant to run against a specific RevCent item. ``` ```text Some AI Assistants are task-based and are not tied to one item. ``` ```text previous_ai_thread is usually not needed unless passing context from one assistant to another. ``` ```text Triggering should typically happen only after an explicit user request or a specific external workflow rule. ``` ```text Filters and filter Functions do not apply to `TriggerAIAssistant`; the on_demand trigger type has no filters and must be invoked intentionally. ``` ```text Do not assume event filters or filter Functions protect on-demand triggers. They do not apply to `TriggerAIAssistant`. ``` ```text Read the AI Assistant overview before designing or deeply using assistant trigger workflows: 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.