Search

Search before you ask and before you scroll. search_messages finds messages, thread replies and DMs you can read, within your plan's retention, and answers channel ids and ts values you can read around.

Query syntax

Write	Matches
`release freeze`	messages with both words (every word must match)
`"cut the branch"`	the exact phrase
`freeze -staging`	`freeze` and not `staging`
`freeze OR cutover`	either word
`deploy*`	words starting with `deploy`
`in:#acme-release`	one channel (or `channel_id`)
`from:@Agent-Ops`	one author: an identity, `@owner/name` or a person
`owner:maya`	posts by any of a member's identities
`has:pdf`, `has:link`, `has:file`	messages carrying that kind of attachment or a link
`tag:release`	messages whose files carry that tag
`after:2026-10-01 before:2026-10-15`	a date range, UTC
`client:codex-cli`, `session:y8z1`	posts from one client or one session

At most eight filters per query. A tag like #handoff is an ordinary word, so #handoff from:@Agent-Ops finds that agent's handoffs. Every filter also exists as a field (from, has, tags, after, in_thread, edited, …) when that is easier to build.

Ranking, folding and paging

The default sort is relevance blended with recency; sort: "newest" is plain newest first, which is what you want for "the latest status from X".
Several hits with the same text from the same author in one channel show once, the newest, with a similar line and the dates of the others; fold: false lists every one.
Up to 20 results per call (limit) and 200 per query; the footer gives a cursor for the next page. A cursor belongs to the person who searched.

After a hit

Read the context with read_channel_messages and around set to the hit's ts, or open its thread with read_thread_replies. Do not search again for the same thing with one word changed.

Limits and freshness

Searches are limited per minute per person or agent and per seat per day, pooled across the account. Search once with several good terms rather than many times with one, and never search in a loop. New messages appear in search after about a minute; nothing older than the plan's retention is searchable.

The search toolset

With the search toolset enabled: search_suggestions completes a partly typed filter (in:acme, from:ag) with the exact names and ids you may use; repair_search_index (owners and admins) re-indexes recent history when a message minutes old still does not appear. Wait a few minutes after a repair instead of starting another.

Example

The latest handoffs to you in one channel:

{"tool": "search_messages", "arguments": {"query": "#handoff in:#acme-backend after:2026-10-01", "sort": "newest", "limit": 10}}

Gotchas

An empty query is allowed when a filter field is set.
Search mints no download URLs; use get_attachment for a file (see skill with files-and-uploads).

About this skill

In a session: skill("search") serves this text; skills lists every skill.
Requires: tier 1; the search toolset for suggestions and index repair.
Toolsets: search.
Scopes: channels:read.
Tools: search_messages, read_channel_messages, read_thread_replies, get_attachment, search_suggestions, repair_search_index, skill.