Skip to main content
Glama

messages_read_history

Read-onlyIdempotent

Read messages from a conversation thread. Use text_contains to find specific messages by content; media_type (photo, document, video, voice, link), date_from/date_to (YYYY-MM-DD, inclusive) and direction (incoming, outgoing) narrow the search and work without text: a photo with no caption sent by the other side in a given month is media_type='photo', direction='incoming' and the dates. A search runs over the loaded part of the conversation and, when that is not all of it, asks the channel's own server (Telegram) to search the rest and stores the hits (a search with text_contains also stores the neighbouring messages of its first 20 hits; one without words stores the hits alone). search_coverage says which: complete = true with a source, or complete = false with the reason, in which case an empty list is not proof the text is absent. sync.loaded_from is the date since which EVERY message is stored (null when unknown); sync.oldest_stored_at is the oldest message stored at all, gaps or not. Returns the most recent messages, including sender info and timestamps. A message in a forum topic (Telegram supergroup with Topics) carries topic_id and, when known, topic (its name); pass that topic_id to messages.send to post into the same topic. A message people reacted to carries reactions (which emoji, who, when): a reaction is often the answer itself, e.g. a thumbs-up under a draft.

Voice calls: each row carries a meta object with allowlisted keys (event_type ∈ 'call_started'|'call_ended'|null, source ∈ 'voice_transcript'|null, call_id, speaker_display_name, duration_seconds, outcome, direction) plus per-message channel. To find calls without scanning every row, use calls.list_history instead.

A file that was never received carries meta.media_skipped (reason, e.g. 'too_large', size_bytes, limit_bytes): the channel did not let us download it, so there is no file to read; the sender can send a link instead.

Usage:

  1. Get thread_id from threads.list first, OR

  2. Use contact_name to auto-resolve thread_id

Examples:

  • User: 'show me messages from chat with [contact]' → read_history(contact_name='[contact]', limit=10)

  • User: 'last 5 messages from thread 571' → read_history(thread_id=571, limit=5)

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "messages_read_history"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of messages to return (default: 10, max: 100)
beforeNoCursor for the page of OLDER messages of a chat read live (`source: "live"`, a Discord channel that is not synced): pass the previous answer's `next_before`. Pages hold at most 100 messages (limit). A stored chat pages with offset instead (the answer's `next_offset`). OMIT for the newest page.
offsetNoNumber of messages to skip (for pagination, default: 0)
date_toNoFilter: only messages sent on or before this day (YYYY-MM-DD, UTC).
date_fromNoFilter: only messages sent on or after this day (YYYY-MM-DD, UTC).
directionNoFilter: 'incoming' = written by the other side, 'outgoing' = written by the owner of the connected account. OMIT for both.
thread_idNoThread ID from threads.list (e.g. '571'), or a channel_ref (e.g. 'telegram:1306644770'). Optional if contact_name provided.
load_untilNoLoad this conversation's history down to this day (YYYY-MM-DD, UTC) in the background, a page at a time. For a channel whose server cannot search (WhatsApp), or to read everything around a date. The answer's `history_load` says how far back the history reaches now and, once the run is over, why it stopped; call again to follow it. OMIT for a normal read.
media_typeNoFilter: only messages carrying this kind of attachment. Works without text_contains, which is how a photo or document sent without a caption is found. OMIT for every kind.
contact_nameNoContact/thread name to search for (optional if thread_id provided). Example: 'Jane Smith', 'John Doe'
in_workspaceNoRun this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected.
text_containsNoFilter: only return messages containing this text (case-insensitive substring match)
include_outgoingNoInclude messages sent by you (default: true)
channel_account_idNoConnected account the conversation must belong to, when you know it (from channels.list). Scopes the lookup to that account, so the same person reached on two connected accounts cannot be confused for one, and a chat that does not exist on this account is 'not found' instead of someone else's thread with a matching id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / before
      Added value: +{
      +  "description": "Cursor for the page of OLDER messages of a chat read live (`source: \"live\"`, a Discord channel that is not synced): pass the previous answer's `next_before`. Pages hold at most 100 messages (limit). A stored chat pages with offset instead (the answer's `next_offset`). OMIT for the newest page.",
      +  "type": "string"
      +}
  2. Changed1 schema field changed
    • addedInput schema / properties / load_until
      Added value: +{
      +  "description": "Load this conversation's history down to this day (YYYY-MM-DD, UTC) in the background, a page at a time. For a channel whose server cannot search (WhatsApp), or to read everything around a date. The answer's `history_load` says how far back the history reaches now and, once the run is over, why it stopped; call again to follow it. OMIT for a normal read.",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
  3. Changed4 schema fields changed
    • addedInput schema / properties / date_from
      Added value: +{
      +  "description": "Filter: only messages sent on or after this day (YYYY-MM-DD, UTC).",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / date_to
      Added value: +{
      +  "description": "Filter: only messages sent on or before this day (YYYY-MM-DD, UTC).",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / direction
      Added value: +{
      +  "description": "Filter: 'incoming' = written by the other side, 'outgoing' = written by the owner of the connected account. OMIT for both.",
      +  "enum": [
      +    "incoming",
      +    "outgoing"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / media_type
      Added value: +{
      +  "description": "Filter: only messages carrying this kind of attachment. Works without text_contains, which is how a photo or document sent without a caption is found. OMIT for every kind.",
      +  "enum": [
      +    "photo",
      +    "document",
      +    "video",
      +    "voice",
      +    "link"
      +  ],
      +  "type": "string"
      +}
  4. Changed1 schema field changed
    • addedInput schema / properties / channel_account_id
      Added value: +{
      +  "description": "Connected account the conversation must belong to, when you know it (from channels.list). Scopes the lookup to that account, so the same person reached on two connected accounts cannot be confused for one, and a chat that does not exist on this account is 'not found' instead of someone else's thread with a matching id.",
      +  "type": "string"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / in_workspace
      Added value: +{
      +  "description": "Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected.",
      +  "type": "integer"
      +}
  6. Added
  7. Removed
  8. First observed

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: searches spill to the channel's server and store hits (plus neighbouring messages for the first 20 text hits), so an empty result is not proof of absence. It also defines search_coverage, sync.loaded_from vs sync.oldest_stored_at semantics, and per-row meta shapes. The only slight tension is describing stored writes on a read-only-annotated tool, which is internal caching rather than an environment mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then organized into distinct paragraphs (search coverage, forum topics, reactions, voice calls, skipped media, usage, examples). It is long and the nested parenthetical about what a search stores is dense, but the length is largely earned by 14 parameters and non-obvious semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by documenting return contents: sender info, timestamps, topic_id/topic, reactions, meta keys for calls, and meta.media_skipped for undownloadable files. An agent can call it and interpret the response without further sources, though it does not cover limits or ordering beyond "most recent".

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description contributes real meaning beyond it: the concrete combination showing media_type works without text (photo + direction + dates finds an uncaptioned photo), date inclusivity, and the before-vs-offset pagination distinction across live and stored chats. thread_id vs contact_name resolution is also clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Read messages from a conversation thread") and immediately scopes it: filters, stored-vs-live search, and returned fields. It also explicitly redirects to a different tool ("To find calls without scanning every row, use `calls.list_history` instead"), so an agent can tell it apart from at least one sibling without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use paths: get thread_id from threads.list or use contact_name to auto-resolve, plus worked examples for both. It also gives when-not guidance for individual parameters (OMIT before for the newest page, OMIT load_until for a normal read, use load_until instead when a channel cannot search), which is stronger than typical routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.