For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Login
HomeDocsAPI ReferenceMCP ServerChat SDKsRelease Notes
HomeDocsAPI ReferenceMCP ServerChat SDKsRelease Notes
  • Introduction
    • Overview
    • Getting started
    • Authentication
    • Data privacy
    • Built-in prompts
    • FAQ
    • Troubleshooting
  • Tools
    • Overview
    • get_ada_configuration
    • get_ada_metric
    • get_available_filters
    • get_conversations
    • get_conversation
    • search_knowledge
    • search_coaching
    • get_improvement_guide
    • list_entities
    • propose_change
    • get_test_cases
    • get_test_runs
    • get_test_run_quota
    • send_feedback
  • Prompt library
    • Overview
    • Improvement recommendations
    • Quick health checks
    • Create visualizations
    • Diagnose performance issues
    • Identify optimization opportunities
    • Review configuration
    • Search knowledge and coaching
    • Test agent responses
    • Deep-dive analysis
Login
LogoLogo
On this page
  • Example prompts
  • Three-phase flow
  • Parameters
  • Supported entity types and operations
  • Knowledge articles
  • Coaching
  • Custom instructions
  • Test cases
  • Test runs
Tools

propose_change

Was this page helpful?
Previous

get_test_cases

Next
Built with

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

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

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.

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

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.