Skip to navigation

list_entities

Lists entities of a given type for discovery and reference. Use the IDs returned here when constructing filters in get_ada_metric or 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 or 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 or 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 and file articles into them with 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

ParameterTypeDescription
entity_typestringOne of channels, topics, variables, playbooks, handoffs, or knowledge_sources.
detailstringOptional. 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_idstringOptional. Fetch a single entity by ID with full detail. Supported for playbooks only.
cursorstringOptional. Opaque cursor returned as next_cursor by the previous call. Omit it to fetch the first page. Pass the same other parameters as the call that returned it. Supported for variables and for a version 2 playbook fetched by entity_id.
limitintegerOptional. variables only. Maximum number of variables in one page, from 1 to 100. Pages are also limited by size, so a page can hold fewer.
name_filterstringOptional. variables only. Case-insensitive substring match against the variable’s name or display name.
scopestringOptional. variables only. Return the variables of one scope: global, meta, sensitive, sensitive_meta, oauth, or auto_capture.

Without entity_id, passing cursor, limit, name_filter, or scope for any entity type other than variables returns an error.

Pagination

Two reads are paged by size: the variables list, and a version 2 playbook fetched by entity_id. If the response has a non-null next_cursor, pass it back as cursor to fetch the next page. Repeat until next_cursor is null before you answer a question about the whole set.

If the tool rejects a cursor, call again without cursor to start from the first page:

  • variables: the tool rejects the cursor if a matching variable is added or removed between calls. A rename does not reject it, and can move a variable to another page, so a variable can be skipped or repeated.
  • Playbook: the tool rejects the cursor if the playbook is saved between calls, for example when it is edited, or enabled or disabled from the dashboard. Enabling or disabling it through the MCP server does not reject the cursor.

An item too large for one page arrives with its longest text cut and a truncated_fields list that names the cut fields. The full text of those fields is not available through this tool. Do not write back an item that has truncated_fields.

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: each page returns entities, total_count, and next_cursor, sorted by name. Each variable has its ID, name, scope (global, meta, auto_capture, sensitive, sensitive_meta, or oauth for the three identifiers), type, and display name (when set).
  • playbooks: playbook ID, name, description, version, and active status. A version 1 playbook fetched by entity_id returns in one response under entities, with its Markdown content. A version 2 playbook fetched by entity_id is paged. The first page holds the playbook’s fields, its sections (ID and title), and a usage_hint. Every page returns items, total_count, and next_cursor. Each item has a part: general_instructions chunks first, then referenced_variable items, then step items. To rebuild the general instructions, join the text of the general_instructions chunks in chunk order. To rebuild the sections, group the steps by section_id. Remove the part and section_id keys from each step before you stage a change to it.
  • 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; external_id is the identifier the Knowledge API 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. At full detail, a website import also carries sync_schedule, the hours, ISO days and timezone it re-crawls on; it is null on every other source. Set it with the same tool. At full detail, every source also carries exclude_selectors, the CSS selectors a website import removes from each page; it is null when a website import has none and on every other source. Set them with the same tool. A website import also carries exclude_paths, the paths it leaves out of a crawl; it is null when the import has none and on every other source.