PhononX/cv-mcp-server

Прикрепляет одну или несколько ссылок URL к существующему сообщению. ИСПОЛЬЗУЙТЕ, КОГДА: добавляете внешние ссылки к сообщению, которое уже существует. ИСПОЛЬЗУЙТЕ ВМЕСТО: create_message_share_link, чтобы поделиться сообщением Carbon Voice наружу. Тот создаёт ссылку, а этот потребляет их. СНАЧАЛА: id берётся из list_messages (поле results[].id). Если у вас его нет, вызовите list_messages первым. ПРИМЕР: {"id":"msg-abc","links":["https://example.com/spec"]} ВОЗВРАЩАЕТ: подтверждение {...} с итоговыми вложениями.

Создаёт элемент действия, опционально привязанный к беседе или папке. ИСПОЛЬЗУЙТЕ, КОГДА: записываете задачу. Требуется только title. Прикрепите его, передав оба параметра container_type и container_id, и свяжите с тем, что его вызвало, с помощью source_message_id. ИСПОЛЬЗУЙТЕ ВМЕСТО: suggest_action_items_from_messages, чтобы задачи извлекались из содержимого сообщений автоматически, а не записывались вручную. ПРИМЕР: {"title":"Send the pricing deck","assigned_to":"user-abc"} ВОЗВРАЩАЕТ: {id, title, status, notes_text?, assigned_to?, due_date?, container_id?, container_type?, creator_id, ...}. Новые элементы изначально имеют статус todo. ОШИБКА BAD_REQUEST: в assigned_to передан недопустимый идентификатор пользователя, или container_id не соответствует container_type. Находите людей с помощью search_users (никогда не передавайте имя), а контейнеры с помощью list_conversations или get_root_folders.

Отправляет личное сообщение одному или нескольким людям по user ID или email. КОГДА ИСПОЛЬЗОВАТЬ: для связи с людьми вне существующего разговора. Укажите получателя через to.user_ids или to.emails. Требуется transcript или links. ВМЕСТО: create_conversation_message, когда разговор уже существует. Личное сообщение начинает отдельную ветку, а не присоединяется к разговору. СНАЧАЛА: to.user_ids берётся из search_users (поле id). Вызовите search_users первым, если у вас нет user ID. ПРИМЕР: {"to":{"user_ids":["user-abc"]},"transcript":"Quick question about the deck."} ВОЗВРАЩАЕТ: {message: {id, link, transcript?, status, conversation_id, created_at, ...}}. ОШИБКА BAD_REQUEST: неверный user ID или не переданы ни transcript, ни links. Найдите людей через search_users. Никогда не передавайте отображаемое имя как user ID. Включите transcript или links.

Создаёт папку в рабочем пространстве, при желании вложенную в другую папку. КОГДА ИСПОЛЬЗОВАТЬ: для организации заметок. Параметры name, type и workspace_id обязательны; добавьте parent_folder_id, чтобы вложить её в другую папку. ИСПОЛЬЗУЙТЕ ВМЕСТО: move_folder, чтобы переместить уже существующую папку. СНАЧАЛА: workspace_id берётся из get_workspaces_basic_info (поле id). Вызовите этот инструмент первым, если у вас нет идентификатора. ПРИМЕР: {"name":"Q4 planning","type":"voicememo","workspace_id":"ws-abc"} ВОЗВРАЩАЕТ: созданную папку той же структуры, что и get_folder.

Создаёт общедоступную ссылку на существующее сообщение (например, голосовую заметку) и возвращает URL. ИСПОЛЬЗУЙТЕ, КОГДА: share_type: "link" для общедоступной ссылки; "forward" для прикрепления ссылки к другому сообщению (также требуется message_id). Также так вы получаете значение share_link_ids. ИСПОЛЬЗУЙТЕ ВМЕСТО: add_attachments_to_message, чтобы прикрепить внешний URL к сообщению, а не публиковать сообщение Carbon Voice наружу. СНАЧАЛА: shared_message_id берётся из list_messages (поле results[].id), вызовите его первым, если у вас его нет. ПРИМЕР: {"shared_message_id":"msg-abc","share_type":"link","access_type":"public"} ВОЗВРАЩАЕТ: {id, link, share_type, access_type, created_by, specified_access?, end_access_at?, revoked_at?, shared_message: {...}}. link: URL для распространения; id: значение share_link_ids, которое принимают другие инструменты. СУЗЬТЕ: передайте response_fields ["id","link","share_type","access_type"], если вам не нужно больше, полный ответ намного больше. ОШИБКА BAD_REQUEST: shared_message_id недействителен, или share_type равен "forward" без message_id. Проверьте идентификатор с помощью get_message; при пересылке также передайте message_id.

Создаёт голосовую заметку либо из текста (произносится через text-to-speech), либо из аудиофайла по URL. ИСПОЛЬЗУЙТЕ, КОГДА: Передайте transcript (2-5000 символов), чтобы Carbon Voice озвучил текст, или https audio_url для загрузки аудио, который имеет приоритет над transcript. Укажите folder_id (его тип должен совпадать) или workspace_id, чтобы сохранить заметку. ИСПОЛЬЗУЙТЕ ВМЕСТО: create_conversation_message для публикации в существующем разговоре или create_direct_message для отправки конкретным людям. Голосовая заметка автономна и хранится в папке или рабочем пространстве. ПРИМЕР: {"transcript":"Reminder to review the pricing deck before Friday."} ВОЗВРАЩАЕТ: {message: {id, link, transcript?, audio_url?, duration_ms, status, type, created_at, ...}}. Первое время status часто имеет значение processing. ОШИБКА INVALID_AUDIO_URL: audio_url не по протоколу https, недоступен, слишком большой, истекло время ожидания, содержит учётные данные или указывает на частный адрес. В сообщении указана причина. Используйте публичный https URL или передайте transcript вместо этого. ОШИБКА BAD_REQUEST: Ни transcript, ни audio_url, ни links не были предоставлены, или transcript выходит за пределы 2-5000 символов. Предоставьте одно из трёх и держите transcript в пределах допустимой длины.

Окончательно удаляет элемент действия. ИСПОЛЬЗУЙТЕ, КОГДА: Элемент был создан по ошибке и вообще не должен существовать. ИСПОЛЬЗУЙТЕ ВМЕСТО ЭТОГО: set_action_item_status со значением done, чтобы завершить элемент. Запись при этом сохраняется. Удаление нельзя отменить, поэтому прибегайте к нему только тогда, когда элемент действительно ошибочный. СНАЧАЛА: id берётся из list_my_action_items (поле results[].id). Вызовите его первым, если у вас его нет. ПРИМЕР: {"id":"ai-abc"} ВОЗВРАЩАЕТ: Подтверждение удаления элемента.

Навсегда удаляет папку, включая все вложенные папки и все их сообщения. ИСПОЛЬЗУЙТЕ, КОГДА: Только когда всё поддерево должно быть уничтожено. Это каскадное действие, и его нельзя отменить. ИСПОЛЬЗУЙТЕ ВМЕСТО: move_folder, чтобы убрать папку с пути, или move_message_to_folder, чтобы сначала перенести её сообщения. Перед вызовом проверьте total_nested_messages_count через get_folder: масштаб каскада легко недооценить. СНАЧАЛА: id берётся из get_root_folders (поле results[].id). Вызовите его первым, если у вас его нет. ПРИМЕР: {"id":"folder-abc"} ВОЗВРАЩАЕТ: Подтверждение удаления.

Получает одну задачу по её ID со всеми деталями. КОГДА ИСПОЛЬЗОВАТЬ: У вас есть ID задачи и нужны её заметки, исполнитель, срок выполнения или исходное сообщение. ИСПОЛЬЗУЙТЕ ВМЕСТО: list_my_action_items или list_action_items, если у вас ещё нет ID - они уже возвращают те же поля для каждой задачи, так что повторный вызов обычно бесполезен. СНАЧАЛА: id берётся из list_my_action_items (поле results[].id) - вызовите его первым, если у вас его нет. ПРИМЕР: {"id":"ai-abc"} ВОЗВРАЩАЕТ: {id, title, status, notes_text?, creator_id, assigned_to?, due_date?, container_id?, container_type?, source_message_id?, last_updated_by, ...}.

Получает результаты AI Action, которые были сгенерированы ранее. ИСПОЛЬЗУЙТЕ, КОГДА: вам нужен существующий результат, а не новый запуск, например, показать, что AI Action уже создал для сообщения или беседы. Комбинируйте prompt_id, message_id и channel_id, чтобы сузить выборку. ИСПОЛЬЗУЙТЕ ВМЕСТО: run_ai_action (или summarize_conversation), чтобы сгенерировать новый результат; этот инструмент только считывает то, что уже существует, и возвращает пустой массив, если ничего не было сгенерировано. ПРИМЕР: {"channel_id":"conv-abc","limit":10} ВОЗВРАЩАЕТ: Массив объектов {id, prompt_id, creator_id, message_ids, channel_id?, workspace_id?, responses: [{language, text?, markdown?, html?, json?}], created_at}. ДЛЯ СУЖЕНИЯ: передавайте response_fields ["id","prompt_id","responses"], если вам не нужно больше; полная полезная нагрузка намного больше.

Получает один разговор по ID со всеми метаданными. ИСПОЛЬЗУЙТЕ, КОГДА: у вас есть conversation_id и нужны его описание, видимость, владелец или название рабочего пространства. ИСПОЛЬЗУЙТЕ ВМЕСТО: get_conversation_users для списка участников. list_messages с conversation_id для сообщений: этот инструмент не возвращает ни того, ни другого. СНАЧАЛА: id берётся из list_conversations (поле results[].id): если у вас нет id, сначала вызовите list_conversations. ПРИМЕР: {"id":"conv-abc"} ВОЗВРАЩАЕТ: {id, name, description?, link, workspace_id, workspace_name, owner_id, type, visibility, ...}.

Перечисляет участников беседы. ИСПОЛЬЗУЙТЕ, КОГДА: нужно выяснить, кто участвует в беседе, или собрать ID пользователей-участников. ИСПОЛЬЗУЙТЕ ВМЕСТО: search_users для поиска людей по имени или email в общем случае. Этот инструмент ограничен одной беседой. СНАЧАЛА: id берётся из list_conversations (поле results[].id). Вызовите list_conversations первым, если у вас нет id. ПРИМЕР: {"id":"conv-abc"} ВОЗВРАЩАЕТ: массив объектов пользователей с id и полями профиля. СУЗЬТЕ: передавайте response_fields ["id","full_name"], если не нужно больше. Полный ответ значительно больше.

Получает идентичность, рабочие пространства и настройки самого вызывающего пользователя. КОГДА ИСПОЛЬЗОВАТЬ: нужно определить, от чьего имени вы действуете, или найти ID рабочих пространств вызывающего пользователя перед вызовом в рамках рабочего пространства. Аргументов не принимает. ЧТО ИСПОЛЬЗОВАТЬ ВМЕСТО: get_user для другого пользователя (требует явного ID). get_workspaces_basic_info, если нужны только ID и названия рабочих пространств. Его ответ гораздо меньше, чем ответ этого инструмента. ПРИМЕР: {} ВОЗВРАЩАЕТ: {success, user: {user_guid, first_name, last_name?, email_txt?, phone_txt?, workspace_guids, identities, entries, environments, lifecycle_events, notification_settings, settings, ...}, settings: {...}}. Этот ответ ОБЪЁМНЫЙ: несколько неограниченных массивов и открытая карта настроек. СУЗИТЬ: передайте response_fields ["user.user_guid","user.first_name","user.email_txt","user.workspace_guids"], если вам не нужно больше. Полный ответ гораздо больше.

Получает метаданные одной папки и, при необходимости, её непосредственные подпапки. ИСПОЛЬЗУЙТЕ, КОГДА: Просматриваете папку. Установите include_first_level_tree: true, чтобы получить подпапки. Оба параметра date и direction молча игнорируются, пока вы этого не сделаете - в документации выше эта оговорка указана только для date. ИСПОЛЬЗУЙТЕ ВМЕСТО: get_folder_with_messages, когда нужны сообщения внутри папки - этот инструмент возвращает только структуру и количество. СНАЧАЛА: id берётся из get_root_folders (поле results[].id) - вызывайте его первым, если у вас его нет. ПРИМЕР: {"id":"folder-abc","include_first_level_tree":true} ВОЗВРАЩАЕТ: {id, name, type, workspace_id, parent_folder_id?, path?, subfolder_ids?, message_ids?, total_nested_folders_count, total_nested_messages_count, subfolders?, ...}.

Получает папку вместе с сообщениями, хранящимися непосредственно в ней. ИСПОЛЬЗУЙТЕ, КОГДА: нужно прочитать содержимое папки. Возвращаются только сообщения на уровне самой папки: вложенные папки не обходятся. ИСПОЛЬЗУЙТЕ ВМЕСТО: get_folder для структуры и количества без тел сообщений. list_messages с folder_id, когда нужна фильтрация по дате или постраничный вывод, которые этот инструмент не поддерживает. СНАЧАЛА: id берётся из get_root_folders (поле results[].id): вызовите его первым, если у вас его нет. ПРИМЕР: {"id":"folder-abc"} ВОЗВРАЩАЕТ: {folder: {...}, messages: [{...}]}. СУЗЬТЕ: передайте response_fields ["folder.id","folder.name","messages"], если вам не нужно больше: полный ответ значительно больше.

Получает одно сообщение по ID, при необходимости дополненное связанными записями. ИСПОЛЬЗУЙТЕ, КОГДА: у вас есть ID сообщения. fields ДОБАВЛЯЕТ связанные данные (conversation, creator, labels), а не сужает ответ. Чтобы сузить ответ, используйте response_fields. ИСПОЛЬЗУЙТЕ ВМЕСТО: list_messages, когда у вас нет ID или нужно несколько сообщений. Он уже возвращает сообщения целиком, поэтому незачем запрашивать каждое из них повторно. СНАЧАЛА: id берётся из list_messages (поле results[].id). Если у вас нет ID, сначала вызовите list_messages. ПРИМЕР: {"id":"msg-abc","fields":"creator"} ВОЗВРАЩАЕТ: {message: {id, transcript?, ai_summary?, audio_url?, creator_id, duration_ms, status, type, attachments?, created_at, ...}}.

Находит существующую ссылку для общего доступа к сообщению по её ID, включая сообщение, которое за ней стоит. ИСПОЛЬЗУЙТЕ, КОГДА: У вас есть ID ссылки общего доступа, и вы хотите получить её URL, настройки доступа или проверить, действительна ли она ещё. Проверьте revoked_at и end_access_at, прежде чем полагаться на неё. ИСПОЛЬЗУЙТЕ ВМЕСТО: create_message_share_link для создания новой ссылки; этот инструмент только читает существующие. get_message, если у вас есть ID сообщения и вам не нужна информация о ссылке. СНАЧАЛА: share_link_id берётся из create_message_share_link (поле id). Если у вас его нет, сначала вызовите create_message_share_link. ПРИМЕР: {"share_link_id":"share-abc"} ВОЗВРАЩАЕТ: ту же структуру, что и create_message_share_link: {id, link, share_type, access_type, revoked_at?, end_access_at?, shared_message: {...}, ...}. СУЗЬТЕ ЗАПРОС: передайте response_fields ["id","link","revoked_at","end_access_at"], если вам не нужно больше. Полная полезная нагрузка значительно больше. ОШИБКА NOT_FOUND: Нет ссылки общего доступа с таким ID, или она больше недоступна. Создайте новую с помощью create_message_share_link; не повторяйте попытку с тем же ID.

Получает до 10 самых свежих сообщений, каждое с conversation, creator и labels. ИСПОЛЬЗУЙТЕ, КОГДА: нужно быстро посмотреть, «что только что произошло». Данные уже объединены, поэтому не нужно дополнительных вызовов, чтобы получить имена creator и conversation. ИСПОЛЬЗУЙТЕ ВМЕСТО: list_messages, когда нужно больше 10 сообщений, любой диапазон дат, пагинация или фильтр, отличный от conversation и language. Этот инструмент ничего из этого не поддерживает. ПРИМЕР: {"conversation_id":"conv-abc"} ВОЗВРАЩАЕТ: {results: [{message: {...}, conversation: {...}, creator: {...}, labels: [...]}]}. Ни total, ни пагинации нет: предел в 10 - это и есть весь ответ.

Перечисляет корневые папки рабочей области для заданного типа папки. ИСПОЛЬЗУЙТЕ, КОГДА: нужно сориентироваться в дереве папок или найти folder_id. type обязателен: voicememo или prerecorded. include_all_tree возвращает и вложенные папки. ИСПОЛЬЗУЙТЕ ВМЕСТО: get_folder, чтобы просмотреть одну папку. get_folder_with_messages, когда нужны сообщения папки, а не её структура. ПРИМЕР: {"type":"voicememo","workspace_id":"ws-abc"} ВОЗВРАЩАЕТ: {type, workspace_id?, include_all_tree?, sort_by, sort_direction, results: [{id, name, parent_folder_id?, subfolder_ids?, total_nested_folders_count, total_nested_messages_count, ...}]}. Не разбивается на страницы - это полный набор. СУЗЬТЕ ВЫБОРКУ: передайте response_fields ["results.id","results.name","results.total_nested_messages_count"], если не нужно больше - полный ответ значительно больше.

Получает полный профиль пользователя по ID: имена, языки, настройки голоса, роли в рабочих пространствах. ИСПОЛЬЗУЙТЕ, КОГДА: у вас уже есть ID пользователя и нужны полные данные. ВМЕСТО ЭТОГО ИСПОЛЬЗУЙТЕ: search_user / search_users, чтобы НАЙТИ пользователя по email, телефону или имени. get_current_user - для вызывающего. Этот инструмент требует явный ID и не будет по умолчанию считать вас текущим пользователем. СНАЧАЛА: id берётся из search_users (поле id) - если id нет, сначала вызовите search_users. ПРИМЕР: {"id":"user-abc"} ВОЗВРАЩАЕТ: {id, first_name, last_name?, languages, voice_gender, workspace_ids, workspace_roles, user_type, created_at, ...}. СУЗЬТЕ ОТВЕТ: передавайте response_fields ["id","first_name","last_name","workspace_ids"], если не нужно больше: полный ответ намного больше.

Перечисляет все рабочие пространства, в которых вы состоите, только по id и названию. КОГДА ИСПОЛЬЗОВАТЬ: Самый дешёвый способ сопоставить название рабочего пространства с ID перед вызовом в рамках рабочего пространства. Не принимает аргументов. ВМЕСТО ЭТОГО ИСПОЛЬЗУЙТЕ: get_current_user, если нужно больше, чем id и названия, но учтите, что ответ гораздо больше, поэтому предпочитайте этот инструмент, когда id достаточно. ПРИМЕР: {} ВОЗВРАЩАЕТ: Массив {id, name}. Больше ничего и без пагинации.

Перечисляет action items, принадлежащие одному контейнеру: беседе, папке или home. ИСПОЛЬЗУЙТЕ, КОГДА: У вас есть container_id, и вы хотите получить его action items. container_type равен channel для беседы, folder для папки или home. Идентификатор беседы - это НЕ идентификатор папки: определяйте container_id с помощью инструмента, соответствующего вашему container_type. Фильтруйте по status или assigned_to (передавайте строку null, если элемент никому не назначен). ВМЕСТО ЭТОГО ИСПОЛЬЗУЙТЕ: list_my_action_items для всего, что назначено вам, независимо от того, где оно находится. СНАЧАЛА: container_id берётся из list_conversations (поле results[].id), когда container_type равен channel. Вызовите этот инструмент первым, если у вас нет container_id. СНАЧАЛА: container_id берётся из get_root_folders (поле results[].id), когда container_type равен folder. Вызовите этот инструмент первым, если у вас нет container_id. ПРИМЕР: {"container_type":"channel","container_id":"conv-abc","status":"todo"} ВОЗВРАЩАЕТ: То же, что и list_my_action_items: {results: [...], total?, results_count?, has_more?, next_cursor?, filters?}. СУЗЬТЕ ОТВЕТ: передавайте response_fields ["results.id","results.title","results.status","results.assigned_to"], если вам не нужно больше. Полный payload гораздо больше.

Перечисляет доступные вам AI-действия (промпты): у каждого есть id, который можно использовать как prompt_id. ИСПОЛЬЗУЙТЕ, КОГДА: Перед вызовом run_ai_action или summarize_conversation, чтобы найти prompt_id. Также чтобы показать пользователю, какие AI-действия существуют. Фильтруйте по owner_type (user = ваши собственные, workspace = общие, system = встроенные Carbon Voice). ИСПОЛЬЗУЙТЕ ВМЕСТО: get_ai_action_responses, если вам нужны уже сгенерированные результаты, а не список доступных действий. ПРИМЕР: {"owner_type":"system"} ВОЗВРАЩАЕТ: Массив {id, name, description?, prompt, owner_type, workspace_id?, response_format?, created_at, last_updated_at}. Используйте id как prompt_id в других местах. СУЗЬТЕ: передайте response_fields ["id","name","description","owner_type"], если не нужно больше: полный ответ значительно больше.

Перечисляет ваши разговоры за последние 6 месяцев, с необязательной фильтрацией по участникам, типу и имени. КОГДА ИСПОЛЬЗОВАТЬ: для поиска conversation_id. Фильтруйте с помощью user_ids вместе с match, types и name. Ваш личный диалог с кем-то задаётся как user_ids: ["<их id>"], types: ["directMessage"]. Вы всегда неявный участник, поэтому никогда не передавайте свой собственный ID. Фильтры объединяются по И; если подходят несколько, уточните, что имелось в виду. ВМЕСТО: get_conversation, когда у вас уже есть ID и нужны полные детали. Этот инструмент возвращает только id, name, workspace_id и type. ПРИМЕР: {"user_ids":["user-abc"],"types":["directMessage"]} ВОЗВРАЩАЕТ: {results_count, results: [{id, name, workspace_id, type}]}, где type: directMessage | customerConversation | namedConversation | asyncMeeting. Без пагинации: results_count равно числу возвращённых после фильтрации результатов. name добавляет unfiltered_count: количество строк, по которым сопоставлялось имя, ПОСЛЕ фильтров user_ids/types. ВСЕГДА проверяйте это значение, прежде чем говорить, что такого разговора не существует. 0 из 47 означает, что ни одна строка не совпала с этой строкой (опечатка или старше 6 месяцев); 0 из 0 означает, что ваши другие фильтры ничего не оставили, а не то, что у вызывающего нет таких разговоров. Расширьте фильтры или уточните; никогда не сообщайте, что разговора не существует.

Перечисляет ваши уведомления во входящих с общим количеством непрочитанных. ИСПОЛЬЗУЙТЕ, КОГДА: отвечаете на вопрос «что я пропустил» или «где меня упомянули». Передайте category: "mentions" для упоминаний. Ответ включает total_unread, поэтому можно сообщить количество без постраничного просмотра. ИСПОЛЬЗУЙТЕ ВМЕСТО: search_message_ids с notified_status, если нужны сами сообщения, а не записи об уведомлениях. search_messages_by_heard_status - для непрослушанных сообщений. ПРИМЕР: {"category":"mentions","limit":25} ВОЗВРАЩАЕТ: {results: [...], total_results, total_unread, filters}. Страницы листаются через skip/limit, а не через курсоры. СУЗЬТЕ ОТВЕТ: передайте response_fields ["results","total_unread","total_results"], если не нужно больше. Полный ответ значительно больше.

Перечисляет сообщения с фильтрацией по дате, диалогу, папке, рабочей области, создателю или языку. Используйте, когда: универсальный инструмент чтения сообщений; полные тела, в том числе расшифровку и AI-сводку. Максимальный диапазон дат: 183 дня. user_ids фильтрует по ОТПРАВИТЕЛЮ: для сообщений, которыми обменивались С кем-то, передайте conversation_id из list_conversations. Используйте presigned URL как есть. Вместо этого используйте: get_recent_messages для быстрого просмотра последних нескольких (жёсткий лимит 10, без постраничной навигации). search_message_ids для фильтров, которые этот инструмент не может выразить: состояние уведомления, упоминания или метки. Сначала: workspace_id берётся из get_workspaces_basic_info (поле id). Если у вас его нет, вызовите этот инструмент первым. ПРИМЕР: {"workspace_id":"ws-abc","start_date":"2026-09-01T00:00:00Z","size":25} Возвращает: {page, size, sort_direction, total, results_count, has_next_page, filters, results: [{id, transcript?, ai_summary?, audio_url?, creator_id, conversation_id?, duration_ms, reply_count, status, type, created_at, ...}]}. Для перехода по страницам используйте has_next_page/total, не угадывайте. СУЗЬТЕ: передайте response_fields ["total","has_next_page","results.id","results.transcript","results.created_at"], если вам не нужно больше. Полный ответ значительно больше.

Перечисляет ваши задачи во всех беседах и папках: назначенные вам, ПЛЮС неназначенные, которые вы создали. ИСПОЛЬЗУЙТЕ, КОГДА: отвечаете на вопрос «что я должен / что у меня в работе» - но сначала проверьте assigned_to, прежде чем считать что-то личным обязательством пользователя: значение null означает пункт, который поднял пользователь, но никто не взял. Фильтруйте по status (todo открыт, suggested предложен ИИ, done завершён). Листайте с помощью starting_after. ИСПОЛЬЗУЙТЕ ВМЕСТО: list_action_items, когда нужна одна конкретная беседа или папка, а не всё, что есть у вас. ПРИМЕР: {"status":"todo","limit":25} ВОЗВРАЩАЕТ: {results: [{id, title, status, notes_text?, assigned_to?, due_date?, container_id?, container_type?, source_message_id?, creator_id, ...}], total?, results_count?, has_more?, next_cursor?, filters?}. Продолжайте листать, пока has_more равно true, передавая next_cursor как starting_after. СУЗЬТЕ: передавайте response_fields ["results.id","results.title","results.status","results.assigned_to","results.due_date"], если не нужно больше - полная полезная нагрузка значительно больше.

Перемещает папку в другую папку или в корень рабочего пространства. ИСПОЛЬЗУЙ, КОГДА: нужно переместить папку. Передай folder_id для новой родительской папки или workspace_id, чтобы переместить папку в корень рабочего пространства — что-то одно, не оба. ИСПОЛЬЗУЙ ВМЕСТО: update_folder_name, чтобы переименовать папку на месте. move_message_to_folder для перемещения одного сообщения, а не папки. СНАЧАЛА: id берётся из get_root_folders (поле results[].id) — вызови его первым, если у тебя нет идентификатора. ПРИМЕР: {"id":"folder-abc","folder_id":"folder-parent"} ВОЗВРАЩАЕТ: перемещённую папку в той же форме, что и get_folder. ОШИБКА BAD_REQUEST: переданы и folder_id, и workspace_id, либо не передано ни одного, либо перемещение вложит папку саму в себя. — Передай ровно одно место назначения.

Перемещает сообщение в папку или в рабочую область. ИСПОЛЬЗУЙТЕ, КОГДА: подшивка памятки. Перемещать можно только сообщения voicememo/prerecorded, созданные вами, и тип сообщения должен совпадать с типом папки. Передайте ровно один из параметров folder_id или workspace_id. ВМЕСТО ЭТОГО ИСПОЛЬЗУЙТЕ: move_folder для перемещения целой папки. create_voicememo_message с folder_id, чтобы подшить памятку сразу при создании, а не перемещать её после. СНАЧАЛА: message_id берётся из list_messages (поле results[].id) — вызовите его первым, если у вас его нет. ПРИМЕР: {"message_id":"msg-abc","folder_id":"folder-abc"} ВОЗВРАЩАЕТ: обновлённое сообщение с новым размещением. ОШИБКА BAD_REQUEST: тип сообщения не voicememo/prerecorded, он не совпадает с типом папки назначения, или переданы оба/ни одного назначения. Проверьте type через get_message и тип папки через get_folder; они должны совпадать. Передайте ровно одно назначение.

Запускает AI Action (промпт) для одного или нескольких конкретных сообщений. ИСПОЛЬЗУЙТЕ, КОГДА: у вас есть конкретные message_ids и prompt_id, и нужно применить AI Action именно к этим сообщениям. ИСПОЛЬЗУЙТЕ ВМЕСТО: summarize_conversation, если нужно суммаризировать весь разговор, а иначе пришлось бы перечислять сообщения вручную: инструмент сам делает эту выборку. СНАЧАЛА: prompt_id берётся из list_ai_actions (поле id). Если у вас нет prompt_id, вызовите list_ai_actions. СНАЧАЛА: message_ids берётся из list_messages (поле results[].id). Если у вас нет message_ids, вызовите list_messages. ПРИМЕР: {"prompt_id":"prompt-abc","message_ids":["msg-1","msg-2"],"language":"english"} ВОЗВРАЩАЕТ: {id, prompt_id, message_ids, creator_id, channel_id?, workspace_id?, responses: [{language, text?, markdown?, html?, json?}], created_at}. Сгенерированный результат находится в responses[], по одной записи на язык. ОШИБКА BAD_REQUEST: prompt_id или один из message_ids недействителен. Вызовите list_ai_actions, чтобы получить допустимые значения prompt_id, и list_messages, чтобы получить допустимые идентификаторы сообщений; не повторяйте запрос с теми же идентификаторами.

Запускает AI Action (Prompt) для одного или нескольких расшаренных сообщений, определяемых по share link ID. ИСПОЛЬЗУЙТЕ, КОГДА: у вас есть share link ID - из create_message_share_link или ссылка, которую вам передали, - и вы хотите применить AI Action к сообщениям, стоящим за ними. ИСПОЛЬЗУЙТЕ ВМЕСТО: run_ai_action, если у вас есть ID сообщений напрямую; переход через share link ничего не даёт, когда у вас уже есть доступ. СНАЧАЛА: share_link_ids берётся из create_message_share_link (поле id) - вызовите его первым, если у вас нет такого ID. СНАЧАЛА: prompt_id берётся из list_ai_actions (поле id) - вызовите его первым, если у вас нет такого ID. ПРИМЕР: {"prompt_id":"prompt-abc","share_link_ids":["share-abc"]} ВОЗВРАЩАЕТ: {share_link_ids, responses: [{language, text?, markdown?, html?, json?}], ...}. ОШИБКА NOT_FOUND: share link ID не существует, либо доступ к нему отозван или истёк. - Создайте новую ссылку через create_message_share_link или проверьте ID с помощью get_message_share_link.

Находит идентификаторы сообщений по статусу уведомлений, упоминаниям, меткам, автору, беседе или рабочей области: возвращает идентификаторы и метаданные курсора. ИСПОЛЬЗУЙТЕ, КОГДА: нужен фильтр, недоступный в list_messages: статус уведомления (notified_status), отметка пользователя (tagged_user_ids) или метки (label_ids). Экономит токены, так как возвращает только идентификаторы: нужные подгружайте через get_message. ИСПОЛЬЗУЙТЕ ВМЕСТО: list_messages, когда нужен только фильтр по диапазону дат, беседе или рабочей области и вы хотите получить полные тексты сообщений одним вызовом. search_messages_by_heard_status для состояния «непрочитано/прослушано», которое этот инструмент не поддерживает. ПРИМЕР: {"notified_status":"notified","limit":50} ВОЗВРАЩАЕТ: {ids: [{...}], has_more, next_cursor?}. Продолжайте запрашивать следующие страницы, пока has_more истинно, передавая next_cursor обратно как next_cursor. ОШИБКА BAD_REQUEST: список идентификаторов содержит имена вместо идентификаторов или превышает 50 записей. Преобразуйте людей в идентификаторы через search_users, а беседы через list_conversations; разбивайте списки длиннее 50.

Находит сообщения по тому, прослушаны ли они, и возвращает счётчики непрослушанных по каждому диалогу. КОГДА ИСПОЛЬЗОВАТЬ: «Что я ещё не прослушал» / «введи меня в курс дела». heardStatus: "unheard" - фильтр непрослушанных. Ответ также содержит unheard_counts_by_channel, так что можно расставить приоритеты между диалогами, не загружая их сообщения. ВМЕСТО ЭТОГО ИСПОЛЬЗУЙТЕ: search_message_ids для состояния уведомлений, упоминаний или якорей дат - этот инструмент не принимает фильтр по дате (см. примечание ниже). list_messages для обычной недавней истории. ПРИМЕР: {"heardStatus":"unheard","limit":25} ВОЗВРАЩАЕТ: {messages: [{message_guid, creator_guid, creator_first_name, channel_guids, transcript_txt, message_ts, heard_status, ...}], unheard_counts_by_channel: {conversation_id: count}, success}. Используйте unheard_counts_by_channel, чтобы решить, куда смотреть в первую очередь. СУЗЬТЕ ЗАПРОС: передайте response_fields ["unheard_counts_by_channel","messages.message_guid","messages.channel_guids","messages.creator_first_name","messages.transcript_txt","messages.message_ts"], если не нужно больше - полный ответ значительно больше.

Находит одного пользователя по email, телефону или имени. ИСПОЛЬЗУЙТЕ, КОГДА: нужно найти ОДНОГО человека. Укажите ровно одно из email, phone или name. Поиск по имени находит только ваши собственные контакты. ИСПОЛЬЗУЙТЕ ВМЕСТО: search_users для нескольких людей за один вызов, он принимает массивы и экономит один запрос на человека. get_user, когда у вас уже есть ID. ПРИМЕР: {"email":"someone@example.com"} ВОЗВРАЩАЕТ: {id, full_name, first_name, last_name?, link, image_url?, languages?, ...}. Используйте id везде, где другой инструмент запрашивает идентификатор пользователя. ОШИБКА NOT_FOUND: Никто не найден, или поиск по имени зацепил не-контакт. Попробуйте email или телефон вместо имени; поиск по имени ограничен вашими контактами.

Определяет несколько пользователей сразу по email, телефонам, ID или именам. КОГДА ИСПОЛЬЗОВАТЬ: превращение списка людей в ID пользователей одним вызовом: правильный первый шаг перед любым инструментом, который принимает ID пользователей. Поиск по имени работает только среди ваших контактов. ИСПОЛЬЗУЙТЕ ВМЕСТО: search_user для одиночного поиска. get_user для полного профиля, когда ID уже есть. ПРИМЕР: {"names":["Brett"]} ВОЗВРАЩАЕТ: массив {id, full_name, first_name, last_name?, link, languages?, ...}. Если по имени найдено несколько кандидатов, уточните, какого человека имели в виду, а не угадывайте. СУЗЬТЕ ВЫБОРКУ: передайте response_fields ["id","full_name"], если не нужно больше: полный ответ значительно больше.

Перемещает элемент действия между suggested, todo и done. ИСПОЛЬЗУЙТЕ, КОГДА: завершаете элемент (done), возвращаете его в работу (todo) или принимаете предложенный ИИ элемент, повышая его с suggested до todo. ИСПОЛЬЗУЙТЕ ВМЕСТО: update_action_item для заголовка, заметок, исполнителя или срока; этот инструмент только меняет статус. СНАЧАЛА: id берётся из list_my_action_items (поле results[].id). Вызовите его первым, если у вас его нет. ПРИМЕР: {"id":"ai-abc","status":"done"} ВОЗВРАЩАЕТ: обновлённый элемент действия, той же структуры, что и get_action_item.

Извлекает пункты действий из ОДНОГО сообщения и немедленно возвращает их. ИСПОЛЬЗУЙТЕ, КОГДА: нужно превратить одно сообщение в задачи - "что она просила меня сделать?". Пункты возвращаются в этом вызове, уже сохранённые со статусом status: "suggested"; переводите нужные в другой статус с помощью set_action_item_status. Предпочитайте этот инструмент suggest_action_items_from_messages, когда сообщение ровно одно, так как он не требует опроса. ИСПОЛЬЗУЙТЕ ВМЕСТО: suggest_action_items_from_messages для двух и более сообщений: он анализирует весь набор сразу и может уловить обязательства, охватывающие несколько сообщений, чего повторные вызовы этого инструмента сделать не могут. create_action_item используйте, когда задача уже известна. СНАЧАЛА: message_id берётся из list_messages (поле results[].id); если у вас его нет, сначала вызовите list_messages. ПРИМЕР: {"message_id":"msg-1"} ВОЗВРАЩАЕТ: Массив созданных пунктов действий, каждый с id, title, assigned_to, due_date, notes_text и status: "suggested". Пустой массив означает, что модель не нашла ничего, что можно было бы выполнить. Извлечение выполняется прямо в этом вызове, так что рассчитывайте, что вызов займёт несколько секунд.

Ставит в очередь извлечение возможных задач из конкретных сообщений с помощью ИИ. Работает в фоне. ИСПОЛЬЗУЙТЕ, КОГДА: нужно превратить разговор в задачи - «о чём мы договорились?». Передайте message_ids для анализа, затем ОПРАШИВАЙТЕ list_my_action_items или list_action_items с status: "suggested", чтобы получить результаты, и повышайте статус нужных с помощью set_action_item_status. ИСПОЛЬЗУЙТЕ ВМЕСТО: suggest_action_items_from_message (для ОДНОГО сообщения) - возвращает задачи напрямую, без опроса. create_action_item, когда задача уже известна и не нужно её выводить, - возвращает задачу синхронно, с id. СНАЧАЛА: message_ids берётся из list_messages (поле results[].id) - сначала вызовите list_messages, если у вас нет message_ids. ПРИМЕР: {"message_ids":["msg-1","msg-2"]} ВОЗВРАЩАЕТ: ТОЛЬКО ПОДТВЕРЖДЕНИЕ - задачи не возвращаются. Извлечение ставится в очередь и работает в фоне, поэтому опрашивайте инструмент вывода списка с status: "suggested", чтобы увидеть результаты.

Создаёт сводку беседы, запуская AI Action по её последним сообщениям. ИСПОЛЬЗУЙТЕ, КОГДА: вам нужна сводка беседы и есть conversation_id. Выбор сообщений выполняется автоматически - опустите message_ids, и будут использованы самые последние сообщения. ИСПОЛЬЗУЙТЕ ВМЕСТО: run_ai_action, если вы уже точно знаете, какие message_ids обрабатывать, или вам нужен AI Action не для сводки. СНАЧАЛА: prompt_id берётся из list_ai_actions (поле id) - если у вас его нет, вызовите list_ai_actions первым. СНАЧАЛА: conversation_id берётся из list_conversations (поле results[].id) - если у вас его нет, вызовите list_conversations первым. ПРИМЕР: {"conversation_id":"conv-abc","prompt_id":"prompt-abc","limit":50} ВОЗВРАЩАЕТ: То же, что и run_ai_action: {id, prompt_id, message_ids, responses: [{language, text?, markdown?, ...}], ...}. ОШИБКА BAD_REQUEST: prompt_id недопустимый идентификатор AI Action. - Вызовите list_ai_actions, чтобы получить допустимые значения prompt_id.

Изменяет заголовок, заметки, исполнителя или срок выполнения элемента действий. КОГДА ИСПОЛЬЗОВАТЬ: при редактировании содержимого элемента. Отправляйте только те поля, которые нужно изменить, пропущенные поля остаются без изменений. ВМЕСТО: set_action_item_status для перемещения элемента между статусами todo / done / suggested; здесь статус не редактируется. СНАЧАЛА: id берётся из list_my_action_items (поле results[].id) — вызовите его первым, если у вас его нет. ПРИМЕР: {"id":"ai-abc","due_date":"2026-10-01"} ВОЗВРАЩАЕТ: обновлённый элемент действий, той же формы, что и get_action_item.

Переименовывает папку. ИСПОЛЬЗУЙТЕ, КОГДА: Изменяется только имя. name - единственное редактируемое поле здесь. ИСПОЛЬЗУЙТЕ ВМЕСТО: move_folder, чтобы изменить расположение папки в дереве. СНАЧАЛА: id берется из get_root_folders (поле results[].id) - вызовите его сначала, если у вас его нет. ПРИМЕР: {"id":"folder-abc","name":"Q4 planning (final)"} ВОЗВРАЩАЕТ: Обновленную папку, той же формы, что и get_folder.