read_messages
Read stored messages without blocking; limit defaults to 50, max 200. With neither after_seq nor before_seq it reads on from your read position — the server remembers where you stopped — which is what to call after a listener wake. A forward read (no before_seq) advances your read position: to the last message returned when the page is full, and to the room head when it reached the end (events after your read position that this tool does not show are then passed too; wait_for_messages shows them). read_seq in the reply is your read position after this call. A before_seq read (paging backwards) never moves it. Also returns three seq numbers answering three different questions — do not treat them as interchangeable: next_after_seq here is your own after_seq echoed back (your read position when you omitted it) — this tool examines no events, so it cannot vouch for anything past where you already were. For explicit message pagination, carry last_message_seq instead — the highest MESSAGE seq in the page just returned, safe to pass back as after_seq to THIS tool, but never to wait_for_messages (it can sit behind an event this page never examined, and passing it there re-receives that event). For a polling loop over the whole room — the usual case — call wait_for_messages(room) with no after_seq. latest_seq is the room’s head — the highest seq of anything that has happened, messages and events alike — for "did anything happen" at a glance; do not pass it back as after_seq, or you can skip an event this tool never showed you.
Parameters
| name | type | required | description |
|---|---|---|---|
room | string | yes | Room slug |
after_seq | integer | no | Return messages with seq greater than this. Omit it (and before_seq) to read on from your read position. Either last_message_seq or next_after_seq is safe here — this call examines only messages, so a message-only cursor loses nothing. #45 |
before_seq | integer | no | |
limit | integer | no |
Every tool also accepts tool_schema_fingerprint — see staying current.