Tools

propose_change

Creates, updates, enables, disables, or deletes Ada entities (knowledge articles, coaching, custom instructions, test cases, playbooks, glossary terms) and triggers test runs.

Call get_improvement_guide before proposing changes so the assistant picks the right entity type and follows Ada’s improvement best practices.

propose_change uses a three-phase flow so field schemas are discovered and changes are confirmed before they are applied.

Example prompts

  • “Create a knowledge article covering our updated return policy, and draft it with the details from this conversation.”
  • “Update the ‘VIP tone’ custom instruction to include the new loyalty-tier language.”
  • “Create a test case from this failed conversation so we catch regressions on the refund flow.”
  • “Run tests for all my billing-related test cases.”
  • “Create a playbook that handles order returns — ask for the order number, look it up, and hand off to an agent if it’s over $500.”
  • “Disable the ‘Password Reset’ playbook while we update the flow, then enable it once the new version is ready.”

Three-phase flow

Every write goes through three steps:

  1. Discover fields. Call with entity_type and operation only (no fields). The tool returns available fields, types, and descriptions for that combination.
  2. Preview. Call again with fields populated (or entity_id only for delete on test cases). The server returns a confirmation preview with a human-readable summary and Confirm/Cancel options — present these to the user. No change is applied yet.
  3. Execute. After the user explicitly confirms, call again with confirmed: true and the same arguments. The tool validates inputs and applies the change.

This structure prevents accidental writes and surfaces what each operation requires before acting.

Parameters

ParameterTypeDescription
entity_typestringThe entity to change. One of: knowledge_article, coaching, custom_instruction, test_case, test_run, playbook, glossary_term.
operationstringWhat to do. Valid operations depend on entity_type (see below).
entity_idstringRequired for update and delete. The ID of the target entity.
fieldsobjectOmit on step 1. Required on steps 2 and 3 for operations that need field values. Keys must match the schema returned in step 1.
confirmedbooleanOmit or false on step 2 to receive a preview. Set to true on step 3 only after explicit user confirmation.

Supported entity types and operations

Entity typeOperations
knowledge_articlecreate, update
coachingcreate, update
custom_instructioncreate, update
test_casecreate, update, delete
test_runcreate
playbookcreate, update, enable, disable
glossary_termcreate, update

Calling an unsupported entity_type × operation combination returns an explicit “not supported” error. Use send_feedback if a capability you need is missing.

Knowledge articles

New knowledge articles are created with enabled: false by default so they don’t affect live traffic until explicitly enabled. Enable them from the Ada dashboard after review.

FieldTypeRequiredDescription
namestringYes (create)The name or title of the article. Max 255 characters.
contentstringYes (create)The article content in markdown format.
languagestringNoIETF BCP 47 language code (for example, en, fr, fr-CA). Defaults to en.
enabledbooleanNoWhether the article is referenced during response generation. Defaults to false.
availability_rulesobject or nullNoAvailability rule controlling which articles the AI Agent can access during a conversation. Send a rule object to attach, null to detach an existing rule, or omit the field to leave any existing rule unchanged. See Availability rules for the full schema.

On update, every field is optional — supply only the fields you want to change. Pass the article ID via entity_id.

Coaching

Both create and update are supported. Coaching is always anchored to a specific AI Agent turn (a generative event) in a real or simulated conversation, so creating coaching requires identifying that event first.

Create

Recommended workflow before creating coaching:

  1. Call get_conversation for the conversation you want to coach.
  2. In the transcript, find the AI Agent response or action entry where the AI Agent went wrong, and confirm it shows is_coachable: true.
  3. Call search_coaching with your intent to check whether similar coaching already exists — update that one instead of creating a duplicate.
  4. Create the coaching against that event.
FieldTypeRequiredDescription
conversation_idstringYesID of the conversation (real or simulated) containing the turn to coach.
generative_actions_event_idstringYesID of the generative event (a single AI Agent turn) this coaching corrects. Take it from the get_conversation transcript — use the entry’s generative_actions_event_id, not the entry’s own id. The entry must show is_coachable: true.
intentstringYesWhat the AI Agent should have done differently — the triggering query, scenario, or topic. Max 500 characters.
coaching_typestringYesThe type of coaching behavior to apply. One of the values below. Immutable after creation.
textstringConditionalThe reply instruction — what the AI Agent should say differently. Required for reply coaching; rejected for all other types. Max 500 characters.
chosen_idstringConditionalID of the target entity. Required for action (action ID), process (process ID), playbook (playbook ID), handoff (handoff ID), and search_knowledge (article ID). Not applicable to reply.
is_livebooleanNoWhether the coaching takes effect on the live AI Agent immediately. Defaults to true. Set to false to stage it without affecting the live AI Agent.

Coaching types — pick the type that matches what went wrong in the coached event:

coaching_typeUse when the AI Agent should have…
reply…changed its text response (tone, phrasing, behavioral instructions). Use only for plain-text replies — not to reference a knowledge article.
action…triggered a specific action (API call, integration) but did not.
process…started or followed a specific multi-step process.
search_knowledge…surfaced a specific knowledge article. Requires chosen_id (the article ID).
handoff…escalated the conversation to a human agent.
playbook…executed a different playbook.

Update

On update, every field is optional — supply only what you want to change. Pass the coaching ID via entity_id; use search_coaching to find IDs. coaching_type cannot be changed.

FieldTypeRequiredDescription
intentstringNoThe user query, scenario, or topic that triggers this coaching. Max 500 characters.
textstringNoThe coaching instruction text. Max 500 characters. Only applicable for reply coaching — rejected for other types.
is_livebooleanNoWhether the coaching is active. Set to true to enable or false to disable.
chosen_idstringNoThe ID of the target entity (action, process, playbook, or handoff response). Only applicable for action, process, playbook, and handoff coaching — rejected for reply and search_knowledge types.

Custom instructions

FieldTypeRequiredDescription
titlestringYes (create)Display name for the custom instruction. Max 150 characters. Must be unique per Agent.
textstringYes (create)The rule the Agent should follow. Max 300 characters.
is_livebooleanNoWhether the instruction is enabled. Defaults to false (draft).
notesstringNoInternal notes about this instruction. Not shown to the Agent.

On update, every field is optional. Pass the custom instruction ID via entity_id.

Test cases

Each test case describes how the AI Agent should respond to a specific scenario and what evaluation criteria determine a pass or fail.

FieldTypeRequiredDescription
namestringYes (create)Descriptive name for the test case. Max 256 characters.
user_messagestringYes (create)The simulated user message sent to the Agent. Max 1024 characters.
success_criteriaarray of stringsYes (create)Criteria used to evaluate the Agent’s response. At least one required. Each criterion is evaluated independently. Max 2048 characters per criterion.
languagestringYes (create)Language code for the test case (for example, en, fr).
channel_idstringNoChannel ID to run the test on. Use list_entities with entity_type='channels' to find IDs.
variablesarrayNoVariable overrides, as objects with variable_id and value. Use list_entities with entity_type='variables' to find IDs.
scenario_goalstringConditionalThe end user’s goal for a multi-turn conversation (for example, “Return a jacket I bought last week”). When provided, the test simulates a full multi-turn exchange instead of a single-turn exchange. Requires the multi-turn simulations feature.

On update, every field is optional. Pass the test case ID via entity_id. On delete, no fields are needed — pass only entity_id.

Test runs

Creating a test_run triggers execution for the specified test case IDs. Use get_test_runs afterward to retrieve pass/fail status, evaluation criteria outcomes, and rationale.

FieldTypeRequiredDescription
test_case_idsarray of stringsYesIDs of the test cases to execute. Use get_test_cases or propose_change with test_case to find or create test cases first.

Playbooks

Create, update, enable, or disable Playbooks from your AI assistant.

Create

New playbooks are created inactive by default. Use the enable operation to activate a playbook after review.

FieldTypeRequiredDescription
namestringYesShort, descriptive name for the playbook. Max 128 characters.
descriptionstringYesExplains when the AI Agent should use this playbook. Max 512 characters. Be specific about the end user intent it handles — this text is used by the routing model to decide which playbook to trigger.
sectionsarray of objectsYesOrdered list of sections containing the playbook steps. See Step types below.
general_instructionsstringNoPersistent guidance injected into every LLM call during playbook execution. Max 4096 characters. Use for tone, behavioral rules, domain context, or references to knowledge articles.

Update

You can change any combination of the name, description, sections, or general instructions. Pass the playbook ID via entity_id.

Inactive playbooks are updated in place — there is no risk because they are not serving conversations. You can optionally activate the playbook as part of the update by setting set_active to true.

Active playbooks are live, so the assistant asks how you want to proceed before making changes:

  • Edit in place (strategy='existing') — applies changes directly to the live playbook.
  • Duplicate (strategy='duplicate') — creates a copy with your changes, leaving the original untouched. You choose whether to activate the copy and whether to deactivate the original (swap) or keep both active.

Enable and disable

Use the enable and disable operations to control whether a playbook is active. Pass only entity_id — no fields are needed.

  • enable — activates the playbook so it can be triggered in conversations.
  • disable — deactivates the playbook without deleting it.

Sections and steps

Each section has an id (unique ObjectId string), a title, and a steps array. Sections are organizational — at runtime they flatten into a single step queue executed top-to-bottom.

Step types

Step typeDescription
sendSend a message. Use message for verbatim text or instruction for LLM-generated responses.
askAsk the end user a question and capture the response into a variable. Supports two modes: reasoning (the AI Agent asks contextually and extracts the value) and exact (the AI Agent asks a verbatim question). Supports accepted_values to constrain responses, fallback_value if the end user never provides a valid answer, and max_reask_attempts (1–20, default 4) to limit retries.
setAssign a variable value without prompting the end user. Requires variable_id and either value (literal) or instruction (LLM extracts value from context). Only global-scoped variables are allowed. Look up variable IDs with list_entities (entity_type='variables').
runExecute a target. Requires target_type (action, handoff, playbook, sms, or exit) and target_id (omit for exit). Look up IDs with get_ada_configuration or list_entities.
if_elseConditional branch. Has a branches array with exactly two entries: the first (if) with conditions and steps, the second (else) with empty conditions and steps. Supports AND/OR operators and nesting up to 10 levels.
go_toJump to another step by target_step_id (must reference an existing step ID in the same playbook).

Glossary term

Create and update glossary terms. The glossary maps colloquial user terms an end user might say to the canonical AI agent terms the Agent should use, optionally per language, plus an optional business definition. Use list_glossary_terms to review existing terms and get_glossary_conflict_guide to check a term against the rest of the configuration before writing.

glossary_term support is gated to the m3 glossary milestone. If it is not enabled for your Agent, create and update return a “not supported” error. Bulk or CSV import is out of scope for this tool — it handles a single term per call.

FieldTypeRequiredDescription
external_idstringYes (create)Client-provided identifier, unique within the glossary. On update, the term is addressed by entity_id; pass external_id only to set or change it.
translation_modestringNocustom — detected user_terms trigger the matching ai_agent_terms. default — user_terms are matched only to surface the definition. Defaults to default.
user_termsarray of objectsConditionalColloquial terms, per language, the Agent detects in an end user message. Each object is {language, term}.
ai_agent_termsarray of objectsConditionalCanonical terms, per language, the Agent should use instead. Each object is {language, term}. Required for custom mode.
definitionstringConditionalBusiness definition or description of the term. In default mode, required unless voice_detection_enabled is set.
voice_detection_enabledbooleanNoPass the term to the voice agent as a key term. Allowed in both modes, but only when the AI Agent has the Voice channel configured — otherwise the field is omitted from the schema and setting it to true is rejected.

Create

Set translation_mode to match the behavior you want, then provide the fields that mode requires:

  • custom — requires both user_terms and ai_agent_terms. Use when detecting a user term should make the Agent respond with the canonical equivalent.
  • default — requires exactly one user_term, no ai_agent_terms, and either a non-empty definition or voice_detection_enabled. Use when a user term should only surface a definition (or be boosted for voice detection), not swap the wording.

Update

On update, every field is optional — supply only what you want to change. Pass the term ID via entity_id; use list_glossary_terms to find IDs. The same mode requirements apply to the resulting term.

Validation rules

  • custom mode requires both user_terms and ai_agent_terms.
  • default mode requires exactly one user_term, no ai_agent_terms, and either a non-empty definition or voice_detection_enabled (a default-mode term with neither does nothing and is rejected).
  • voice_detection_enabled is allowed in both modes; voice-enabled terms must use a restricted character set. It requires the AI Agent to have the Voice channel configured — setting it to true on an Agent without Voice is rejected.
  • Every term’s language must be enabled for the Agent (one of its supported languages).