propose_change

Creates, updates, or deletes Ada entities (knowledge articles, coaching, custom instructions, test cases) and triggers test runs. propose_change uses a two-phase flow so the field schema is discovered before changes 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.”

Two-phase flow

Every propose_change call goes through two steps:

Discover fields. Call with entity_type and operation only (no fields). The tool returns the available fields, their types, and descriptions for that combination.
Execute. Call again with the same entity_type and operation, plus a populated fields object. The tool validates the inputs and applies the change.

This structure surfaces what each write requires before acting, which reduces errors from guessing field names or formats.

Parameters

Parameter	Type	Description
`entity_type`	string	The entity to change. One of: `knowledge_article`, `coaching`, `custom_instruction`, `test_case`, `test_run`.
`operation`	string	What to do. Valid operations depend on `entity_type` (see below).
`fields`	object	Optional on phase 1. Required on phase 2. Object whose keys match the schema returned in phase 1.

Supported entity types and operations

Entity type	Operations
`knowledge_article`	`create`, `update`
`coaching`	`update`
`custom_instruction`	`create`, `update`
`test_case`	`create`, `update`, `delete`
`test_run`	`create`

Calling an unsupported entity_type × operation combination returns an explicit “not supported” error.

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.

Field	Type	Required	Description
`name`	string	Yes (create)	The name or title of the article. Max 255 characters.
`content`	string	Yes (create)	The article content in markdown format.
`language`	string	No	IETF BCP 47 language code (for example, `en`, `fr`, `fr-CA`). Defaults to `en`.
`enabled`	boolean	No	Whether 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

Only update is supported — coaching entries are created from the Ada dashboard or through conversation-level coaching workflows.

Field	Type	Required	Description
`intent`	string	No	The user query, scenario, or topic that triggers this coaching. Max 500 characters.
`text`	string	No	The coaching instruction text. Max 500 characters. Only applicable for `reply` coaching — rejected for other types.
`is_live`	boolean	No	Whether the coaching is active. Set to `true` to enable or `false` to disable.
`chosen_id`	string	No	The 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.

Pass the coaching ID via entity_id. Use search_coaching to find coaching IDs.

Custom instructions

Field	Type	Required	Description
`title`	string	Yes (create)	Display name for the custom instruction. Max 150 characters. Must be unique per Agent.
`text`	string	Yes (create)	The rule the Agent should follow. Max 300 characters.
`is_live`	boolean	No	Whether the instruction is enabled. Defaults to `false` (draft).
`notes`	string	No	Internal 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.

Field	Type	Required	Description
`name`	string	Yes (create)	Descriptive name for the test case. Max 256 characters.
`user_message`	string	Yes (create)	The simulated user message sent to the Agent. Max 1024 characters.
`success_criteria`	array of strings	Yes (create)	Criteria used to evaluate the Agent’s response. At least one required. Each criterion is evaluated independently. Max 2048 characters per criterion.
`language`	string	Yes (create)	Language code for the test case (for example, `en`, `fr`).
`channel_id`	string	No	Channel ID to run the test on. Use `list_entities` with `entity_type='channels'` to find IDs.
`variables`	array	No	Variable overrides, as objects with `variable_id` and `value`. Use `list_entities` with `entity_type='variables'` to find IDs.
`scenario_goal`	string	Conditional	The 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.

Field	Type	Required	Description
`test_case_ids`	array of strings	Yes	IDs of the test cases to execute. Use `get_test_cases` or `propose_change` with `test_case` to find or create test cases first.