search_message_ids
Find message IDs by notification status, mentions, labels, creator, conversation, or workspace. Use when list_messages lacks these filters, then hydrate with get_message.
Instructions
Find message IDs by notified state, mentions, labels, creator, conversation or workspace — returning IDs plus cursor metadata.
USE WHEN: Any filter list_messages cannot express: whether you were notified (notified_status), whether you were tagged (tagged_user_ids), or by label_ids. Cheap in tokens because it returns IDs only — hydrate the ones you need with get_message.
USE INSTEAD: list_messages when a date range, conversation or workspace filter is all you need and you want full message bodies in one call. search_messages_by_heard_status for unread/listened state, which this tool cannot filter on.
EXAMPLE: {"notified_status":"notified","limit":50}
RETURNS: {ids: [{...}], has_more, next_cursor?}. Keep paging while has_more is true, passing next_cursor back as next_cursor.
ERROR BAD_REQUEST: An ID list contains names rather than IDs, or exceeds 50 entries. — Resolve people to IDs with search_users and conversations with list_conversations; split lists longer than 50.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of message IDs to return (max 100). | |
| has_notes | No | Filter by whether the message has notes attached. | both |
| label_ids | No | Only messages carrying these labels. Max 50 entries. Requires IDs, not names. | |
| creator_ids | No | Only messages created by these users. Max 50 entries. Requires IDs, not names. | |
| next_cursor | No | Pass the `next_cursor` from a previous response to fetch the next page. | |
| workspace_ids | No | Only messages in these workspaces. Max 50 entries. Requires IDs, not names. | |
| sort_direction | No | Direction to walk from the anchor. | newer |
| notified_status | No | Filter by whether you were notified about the message. `notified` = messages you were notified about, `not_notified` = the rest, `both` = no filter. | both |
| response_fields | No | Dot-path allowlist to shrink the response, e.g. ["results.id","total"]. Omit for the full payload. | |
| tagged_user_ids | No | Only messages where these users were tagged/mentioned. Max 50 entries. Requires IDs, not names. | |
| conversation_ids | No | Only messages in these conversations. Max 50 entries. Requires IDs, not names. | |
| created_or_updated_at | No | ISO 8601 timestamp anchor; a UTC `Z` suffix or a numeric offset both work. Combined with `sort_direction` to page backwards or forwards from a point in time. |