Tools

propose_change

Creates, updates, enables, disables, or deletes Ada entities (knowledge articles, coaching, custom instructions, test cases, playbooks) 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.
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

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.

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