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

# list_entities

Lists entities of a given type for discovery and reference. Use the IDs returned here when constructing filters in [`get_ada_metric`](/mcp/tools/get-ada-metric) or [`get_conversations`](/mcp/tools/get-conversations), or when targeting specific channels, topics, or variables in prompts.

## Supported entity types

* **`channels`** — All communication channels configured for the AI Agent (native and custom).
* **`topics`** — Generated topics and categories. Use topic IDs with the `TOPICS` filter in [`get_ada_metric`](/mcp/tools/get-ada-metric) or [`get_conversations`](/mcp/tools/get-conversations).
* **`variables`** — Conversation variables in the scopes an availability rule can reference (`global`, `meta`, `sensitive`, `sensitive_meta`, and the `oauth` identifiers `channel`, `chatter_id` and `end_user_id`), plus `auto_capture`, which is listed for filters and metrics but cannot be used in a rule. Use the variable ID as `variable.id` in `availability_rules`, or with the `VARIABLE` filter in [`get_ada_metric`](/mcp/tools/get-ada-metric) or [`get_conversations`](/mcp/tools/get-conversations).
* **`playbooks`** — AI Agent playbooks. Returns a summary by default (ID, name, description, version, active status). Pass `entity_id` to get full detail including steps and structure.
* **`handoffs`** — Handoff responses configured for the AI Agent, including active status.
* **`knowledge_sources`** — Knowledge sources the Agent's articles are grouped under, including the default **Created in Ada**. Create new ones with [`edit_agent_config`](/mcp/tools/edit-agent-config) and file articles into them with [`edit_agent_behavior`](/mcp/tools/edit-agent-behavior).

## Example prompts

* "What channels are configured on our Agent?"
* "List all topics configured on our Agent."
* "List all autocapture variables so I can filter conversations by one of them."
* "Show me the full details of playbook `abc123`."
* "What handoff responses are available?"
* "Which knowledge sources does our Agent have?"

## Parameters

| Parameter     | Type   | Description                                                                                                                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_type` | string | One of `channels`, `topics`, `variables`, `playbooks`, `handoffs`, or `knowledge_sources`.                                                                                             |
| `detail`      | string | Optional. `full` (default) returns all available fields including type-specific metadata. `minimal` returns ID and name, plus `type` for `tools` and `status` for `knowledge_sources`. |
| `entity_id`   | string | Optional. Fetch a single entity by ID with full detail. Supported for `playbooks` only.                                                                                                |

## Response

Returns the list of entities for the chosen type. Fields vary by `entity_type` and `detail`:

* **`channels`** — channel ID, name, type, modality, and description.
* **`topics`** — topic ID, name, category, and conversation volume (when available).
* **`variables`** — variable name, scope (`global`, `meta`, `auto_capture`, `sensitive`, `sensitive_meta`, or `oauth` for the three identifiers), type, and description (when available).
* **`playbooks`** — playbook ID, name, description, version, and active status. When fetched by `entity_id`, includes full step structure.
* **`handoffs`** — handoff ID, name, description, and active status.
* **`knowledge_sources`** — source ID, name, `external_id`, `status`, `last_sync`, and `metadata`. At `minimal` detail: ID, name, and `status`. Two IDs are returned because two systems address a source: `id` is the Ada ID for MCP tools such as `knowledge_source_id` in [`edit_agent_behavior`](/mcp/tools/edit-agent-behavior); `external_id` is the identifier the [Knowledge API](/reference/knowledge/sources) uses. `status` is `null` for a healthy source. A non-null value (`deleting` or `delete_failed`) means the source is being deleted or its deletion failed. Do not file articles into a source with a non-null `status`. At `full` detail, `availability_rules` holds the rules that the Knowledge API, Apps and website imports copy onto every new article they create under the source. The key is absent when the source has none, and `null` when its stored rules cannot be expressed in the rule schema. Set them with [`edit_agent_config`](/mcp/tools/edit-agent-config).