> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Tools overview

The MCP server exposes a set of tools that your AI assistant (Claude, ChatGPT, Gemini, etc.) can call to read Agent configuration, query metrics, pull conversation data, manage test cases and test runs, and change the Agent itself. Each tool page documents parameters, response shape, and example usage.

Changes to Agent behavior are staged on a change set and tested before they go live. Changes to settings apply immediately. See [`edit_agent_behavior`](/mcp/tools/edit-agent-behavior) and [`edit_agent_config`](/mcp/tools/edit-agent-config).

## Tool index

### Configuration

| Tool                                                        | What it does                                                                        |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [`get_ada_configuration`](/mcp/tools/get-ada-configuration) | Fetches playbooks (summary), actions, custom instructions, and company description. |

### Metrics and conversations

| Tool                                                        | What it does                                                                                          |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [`get_ada_metric`](/mcp/tools/get-ada-metric)               | Returns AR rate, CSAT, containment, and engaged conversation volume with conversation-level metadata. |
| [`get_available_filters`](/mcp/tools/get-available-filters) | Lists supported filter types and operators for conversation queries.                                  |
| [`get_conversations`](/mcp/tools/get-conversations)         | Returns many conversations at `IDS_ONLY` or `SUMMARY` detail.                                         |
| [`get_conversation`](/mcp/tools/get-conversation)           | Returns the full transcript for a conversation ID.                                                    |

### Knowledge and coaching

| Tool                                                        | What it does                                                                              |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [`search_knowledge`](/mcp/tools/search-knowledge)           | Searches existing knowledge articles.                                                     |
| [`search_coaching`](/mcp/tools/search-coaching)             | Searches existing coaching entries.                                                       |
| [`get_improvement_guide`](/mcp/tools/get-improvement-guide) | Returns Ada's entity improvement guide and best practices. Call before proposing changes. |

### Entity discovery

| Tool                                        | What it does                                                                                                                                                              |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`list_entities`](/mcp/tools/list-entities) | Lists channels, topics, variables, custom metrics, scorecards, Playbooks, handoffs, processes, custom instructions, tools, or knowledge sources configured for the Agent. |

### Testing

| Tool                                                  | What it does                                                             |
| ----------------------------------------------------- | ------------------------------------------------------------------------ |
| [`get_test_cases`](/mcp/tools/get-test-cases)         | Retrieves test cases, optionally filtered by name or grouped by channel. |
| [`get_test_runs`](/mcp/tools/get-test-runs)           | Retrieves test run results, pass/fail status, and evaluation rationale.  |
| [`get_test_run_quota`](/mcp/tools/get-test-run-quota) | Returns daily test run quota, usage, and remaining runs.                 |

### Writes

Write tools require an Owner or Admin role when using OAuth. See [Permissions](/mcp/introduction/authentication#permissions).

| Tool                                                    | What it does                                                                                                                                                                                 |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`edit_agent_behavior`](/mcp/tools/edit-agent-behavior) | Stages changes to knowledge articles, coaching, Playbooks, Actions, and custom instructions on a change set, then promotes, reverts, or discards it.                                         |
| [`edit_agent_config`](/mcp/tools/edit-agent-config)     | Creates, updates, enables, disables, or deletes settings such as test cases, topics, custom metrics, and scorecards; creates knowledge sources; and triggers test runs. Applies immediately. |

### Change sets

| Tool                                                                | What it does                                                                                                                       |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [`list_agent_changesets`](/mcp/tools/list-agent-changesets)         | Lists change sets by status, or returns one with a before-and-after comparison of its staged edits.                                |
| [`compare_changeset_metrics`](/mcp/tools/compare-changeset-metrics) | Compares a change set against baseline over a date range, returning both cohorts side-by-side with the difference for each metric. |

### Feedback

| Tool                                        | What it does                                                                                                               |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| [`send_feedback`](/mcp/tools/send-feedback) | Sends structured feedback directly to Ada's development team when MCP tools are blocked, unclear, or missing capabilities. |

## Typical call patterns

* **Performance analysis**: `get_available_filters` → `get_conversations` → `get_conversation` (for selected IDs) → `get_ada_metric` for aggregates.
* **Configuration review**: `get_ada_configuration` → `search_knowledge` / `search_coaching` to cross-reference existing content.
* **Improvement recommendations**: [`get_improvement_guide`](/mcp/tools/get-improvement-guide) → `get_ada_metric` (to find under-performing conversations) → `get_conversation` (for transcripts) → `get_ada_configuration` (to identify gaps) → `search_knowledge` / `search_coaching` → `edit_agent_behavior` to stage a change, test it, and promote it.
* **Test-driven development**: `get_conversations` (production samples) → `edit_agent_config` with `test_case` → `edit_agent_behavior` to stage the fix → `edit_agent_config` with `test_run` pinned to the change set → `get_test_runs` to review results → `edit_agent_behavior` with `promote`.