Skip to main content
Glama

dialogbrain

by io.github.saloprj
OverviewDiscussionsAdmin

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.

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.

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)

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.7/5.0
Behavior5/5

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

Goes far beyond the readOnly/idempotent annotations: it discloses that searches run locally over the loaded part and then fall through to Telegram's own server, that hits (and neighbouring messages of the first 20 text hits) are stored, and that search_coverage can be complete=false, in which case an empty list does not prove absence. It also documents the meta allowlist for voice-call rows and the distinction between sync.loaded_from and sync.oldest_stored_at.

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 purpose then filtered-search semantics, and most sentences carry real information. It is nonetheless dense and long, with the search_coverage/sync paragraph packed tightly enough to be one pass of re-reading; a small amount could be trimmed or split without losing meaning.

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

Completeness5/5

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

For a 14-parameter tool with no output schema, the description covers what comes back (recent messages with sender info and timestamps), how coverage and sync state are reported, paging mechanics, and the call-row metadata. An agent has everything needed to call it correctly and to interpret an empty result.

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

Parameters5/5

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

Schema coverage is already 100%, but the description still adds semantics the schema doesn't carry: media_type and direction work together to locate an uncaptioned photo without any text, dates are inclusive, before applies only to live-paged chats while offset applies to stored ones, and load_until loads in the background and must be re-called to follow the run.

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

Purpose4/5

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

Opens with a specific verb+resource ('Read messages from a conversation thread') and explicitly routes call-history lookups away to calls.list_history. It does not, however, distinguish itself from other retrieval siblings such as search_messages or group_preview_messages, which an agent could plausibly confuse with this tool.

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?

Gives explicit preconditions (get thread_id from threads.list, or use contact_name to auto-resolve) with two worked examples, plus when-to-use rules for load_until (channels that cannot search server-side, or reading everything around a date), media_type without text_contains, and the pointer to calls.list_history for call lookups. Nothing about selection is left implicit.

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

All dialogbrain toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources