Tools

propose_change

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

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

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.