Returns each folder's id, name, emoji and rules: which chats it names, which it excludes, and which whole categories it admits (contacts, non-contacts, groups, channels, bots) or withholds (muted, read, archived). Use when the user asks how their chat folders are set up or which folder id to filter by. Do not use this to put a chat into a folder; that is telegram_plan_folder_add, and listing the chats in one folder is telegram_chats with a folder argument. The ids are what chats and inbox take as folder. A folder is the user's own sorting, not a permission: chats this configuration may not enumerate stay hidden inside it.

Returns the account's dialogs with unread counts, so a title can be turned into the chat_id every other operation needs. Use when the user wants a chat list, unread counts, or a chat id from a title. Do not use this to read messages; call telegram_chat_read once the chat is known, or telegram_search to find text. Private conversations are excluded unless safety.read.enumerate_dms permits them.

Fetches up to 500 messages with attachment metadata, reaction counts, a permalink per message and, where Telegram reports it, whether each one has been read. Use when the user asks what was said in one known chat. Do not use this to find a chat by name; call telegram_chats first, or telegram_search when the words matter more than the latest page. Reading does not mark the chat read; that is telegram_plan_mark_read. Page backwards with before_id; a t.me link to a message starts the page at that message. In a forum, topic_id (or a topic link) limits the page to one topic — without it the topics arrive interleaved. Reading never marks anything as seen.

List the members of a group or channel, with their roles. Use when the user asks who is in a group or channel, or which members are admins. Do not use this to resolve one username; call telegram_whois, or telegram_chat_read to see what those people wrote.

Effect local_write: it writes a SQLite file on this machine, never anything on Telegram. Use when the user wants one chat copied to the local archive so later questions do not hit Telegram. Do not use this to search that copy; call telegram_archive_search after a sync, or telegram_chat_read for a live page. One chat per call, named explicitly — there is no background sync and nothing is archived that was not asked for. A repeat call fetches only what is new (the stored watermark bounds the request) and then backfills older messages until the per-call budget runs out; complete says whether the beginning of the history has been reached. Attachments are never downloaded, only their metadata. The read policy is checked before the first request, and again on every read of the archive afterwards.

Costs no Telegram request at all, which is what makes regular expressions, sender filters and date ranges possible — Telegram's own search matches text only. Use when the user wants a regular expression, a sender, or a date range over messages already archived. Do not use this for a live Telegram search; call telegram_search, or telegram_archive_sync first when the chat is not archived. Every result is checked against the current read policy for its own chat, so a chat archived while it was permitted and closed since is withheld and counted. The answer always carries meta.source: archive and the timestamp of the oldest sync it covers: an archive result mistaken for a live one is stale state reported as current.

One row per archived chat with its message count, id watermarks, whether the backfill reached the beginning, and when it was last synchronised. Use when the user asks what the local archive holds, how many messages, or when a chat was last synced. Do not use this to search the text; call telegram_archive_search, or telegram_archive_forget to erase a chat from disk. Filtered by the current read policy like every other read; chats it withholds are counted, and archive forget is how they leave the disk.

Effect local_write. Use when the user wants one chat's archived messages erased from this machine. Do not use this to leave the chat on Telegram; call telegram_plan_leave_chat, or telegram_archive_status to see what is stored first. Deliberately not gated on the read allowlist: a chat just removed from it is precisely the one whose copy on disk ought to go, and refusing would strand personal data with no way to remove it. Idempotent — forgetting a chat that was never archived reports forgotten: false rather than failing.

Returns identity only: id, kind, handle, bot flag, and shared groups for users. Use when the user gives a username, numeric id, or invite link and asks who or what it is. Do not use this to join the chat; joining is telegram_plan_join_chat, and a member list is telegram_chat_members. An invite link is described with CheckChatInvite and is never joined — joining is a write and goes through a plan.

Reports every registered account with its sign-in state, lock state and whether the safety configuration permits using it. Use when the user asks which Telegram accounts are configured, signed in, or locked. Do not use this to list devices on one account; call telegram_sessions, or telegram_chats to see that account's dialogs. Local only unless probe is set.

A compact, ranked summary of conversations with unread messages, mentions or reactions — one row per chat, not raw history. Use when the user asks what is waiting, what they missed, or which chats need a reply. Do not use this to read one chat's history; call telegram_chat_read, or telegram_mentions when the question is who mentioned them. Mentions rank first, then unread reactions on this account's own messages, then volume. Use telegram_mentions to see the messages behind those two counts. Reading the inbox never marks anything as seen.

Writes to a server-chosen path under a generated name and returns an opaque artifact_id. Use when the user wants the file attached to one message saved on this machine. Do not use this to turn a voice message into text; call telegram_media_transcribe, or telegram_chat_read when the attachment metadata is enough. There is no destination parameter: a caller-chosen path would let this tool overwrite configuration, plans or the session file itself. Size, timeout and total quota all apply.

The messages behind telegram_inbox's mention and reaction counters: who mentioned or replied to this account and what they said, and who reacted to its own messages with which emoji. Use when the user asks where they were mentioned or which of their messages got a reaction. Do not use this for a ranked overview of every unread chat; call telegram_inbox, or telegram_message_reactions for the counts on one known message. Telegram counts these separately from plain unread, which is what makes them a signal rather than volume. Reading them marks nothing as seen — the badge on the owner's own phone is unchanged.

Returns the per-emoji counts on a single message, plus whichever recent reactors Telegram already attached to it. Use when the user asks how people reacted to one message. Do not use this to add or remove a reaction; those are telegram_plan_react_message and telegram_plan_unreact_message, and unread reactions across chats are telegram_mentions. The full list of who reacted is never requested — where it is unavailable the payload says so. Reading reactions marks nothing as seen and adds no reaction.

What was started and never sent, newest first, with the chat each draft belongs to. Use when the user asks about text they started and never sent. Do not use this for messages queued to go out later; call telegram_scheduled, or telegram_chat_read for messages that were actually sent. Gated like a dialog listing: enumeration, then the hard floor per row, then the read policy of the draft's own chat — a draft in Saved Messages or Service Notifications is never listed or counted. Reading a draft does not clear it; nothing here can.

The chat's scheduled queue, soonest first, with the time each message is due — or a flag where Telegram will send it as soon as the other person comes online. Use when the user asks what is queued to send later in one chat. Do not use this for unsent drafts; call telegram_drafts, or telegram_plan_schedule_message to queue a new message. One chat at a time, because Telegram keeps no global list. Cancelling or sending one early is not part of this project.

Scoped to a chat, the read policy is checked once for that chat, and context may bring back the messages either side of each match, marked match: false. Use when the user asks to find messages by words, in one chat or across the account. Do not use this for a regular expression or for text already copied locally; call telegram_archive_search for that, or telegram_chat_read to page the latest history. Unscoped, every result is checked against the policy for its own chat and the number withheld is reported.

Device, application, coarse location, first sign-in and last activity for every authorisation, current one first. Use when the user asks which devices or apps are signed in, or whether one of them is unfamiliar. Do not use this to end a session; this server has no such tool, and telegram_fleet only says whether the local account is usable. The address is cut to its network and the authorisation hash is not returned at all: nothing in this project ends a session, and that identifier has no other use.

A forum keeps a separate thread per topic, and a flat read interleaves them into a conversation nobody had. Use when the user asks for the topic list of a forum, or which topic id to read. Do not use this to read the messages inside a topic; call telegram_chat_read with that topic id. This returns id, title, icon, per-topic unread and mention counts, whether the topic is closed or hidden, when it was created and a permalink — so chat read --topic-id can page one of them. A chat that is not a forum is refused with that reason, not with an empty list.

Downloads the audio like media fetch does, then runs Whisper (model 'small') in a separate optional Docker image with no network at all, so the recording never leaves this host. Use when the user asks what a voice message or audio file says. Do not use this only to download the file; call telegram_media_fetch, and do not use it for an ordinary text message; call telegram_chat_read. The transcript is a stranger's words and is marked as untrusted content. Requires the optional image: build it with make transcribe-image and fetch the model once with make transcribe-model; without it the operation refuses and says so.

Blocks until a message arrives in a permitted chat, then returns the whole burst in one answer: replies that land within debounce_sec of each other wake the caller once, not once each. Use when the user wants to wait for the next message instead of asking again. Do not use this to look at what already arrived; call telegram_inbox or telegram_chat_read. The call holds the account until it returns. Always returns within timeout_sec (at most 300s); an empty result at the ceiling is an answer, not an error, and says how long it waited. Messages from chats the policy refuses are not reported at all — not even as the fact that something happened. Reading never marks anything as seen. Note that the account's session is held for the duration of the wait, so nothing else can use it meanwhile.