Fast MCP Telegram

Search messages globally

search_messages_globally

Read-onlyIdempotent

Instructions

Search all Telegram chats at once (not scoped to one chat). Comma-separated query terms; optional filters by date, chat kind, and public username. Results are ordered by ascending date-time (oldest first); limit selects the newest N. Success: message list and metadata dict. Global search ignores include_total_count. Full documentation: https://github.com/leshchenko1979/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum messages to return (recommended 50 or less).
`query`	Yes	Search terms, comma-separated for multiple terms (OR-style global search). Required.
`public`	No	If true, prefer chats with a public username; if false, without. Does not apply to private DMs. Omit to skip this filter.
`max_date`	No	Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound.
`min_date`	No	Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound.
`chat_type`	No	Comma-separated chat kinds: private, bot, group, channel. Case-insensitive; extra spaces allowed.
`auto_expand_batches`	No	Extra search batches to run when filters narrow results. Higher values may return more matches at the cost of latency.
`include_total_count`	No	If true, response may include total_count where supported (per-chat search; ignored for global search).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`ok`	No
`code`	No
`error`	No
`action`	No
`params`	No
`_warning`	No
`has_more`	No
`messages`	No
`exception`	No
`operation`	No
`error_code`	No
`total_count`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.37.0Jun 20, 2026
RemovedJun 18, 2026

Changed3 schema fields changedv0.36.0Jun 18, 2026

removedOutput schema / additionalProperties
```
Removed value: -true
```

addedOutput schema / description

Added value: +"Return type for ``search_messages_globally`` and ``get_messages``."

addedOutput schema / properties

Added value: +{
+  "_warning": {
+    "type": "string"
+  },
+  "action": {
+    "type": "string"
+  },
+  "code": {
+    "type": "integer"
+  },
+  "error": {
+    "type": "string"
+  },
+  "error_code": {
+    "type": "string"
+  },
+  "exception": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "has_more": {
+    "type": "boolean"
+  },
+  "messages": {
+    "items": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "ok": {
+    "type": "boolean"
+  },
+  "operation": {
+    "type": "string"
+  },
+  "params": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "total_count": {
+    "type": "integer"
+  }
+}

First observedv0.21.0May 28, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Adds value beyond annotations (which only cover readOnly/idempotent/openWorld): discloses ordering ('ascending date-time, oldest first'), that 'limit selects the newest N', the return shape ('message list and metadata dict'), and the ignored-parameter caveat. Notably omits permission or rate-limit context, so it is strong but not exhaustive.

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-loads the core purpose and packs scope, filters, ordering, and return shape into compact sentences. Slightly dense but every clause carries information; the doc link is the only marginal element.

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?

For an 8-parameter global search with a full output schema and rich annotations, the description covers scope, ordering, limit semantics, and the count caveat. Missing only explicit sibling routing ('use X instead when...'), which is a minor gap.

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

Parameters3/5

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

Schema coverage is 100%, so parameters are fully documented in the schema; the description only restates query/media filters and the include_total_count caveat. Per the baseline rule, 3 is appropriate when the schema does the heavy lifting.

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 and resource ('Search all Telegram chats at once') and explicitly disambiguates scope with '(not scoped to one chat)', distinguishing it from chat-scoped siblings like get_messages and find_chats.

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

Usage Guidelines3/5

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

Implies global scope usage and warns 'Global search ignores include_total_count', but never names an alternative sibling (e.g., when to use get_messages or find_chats instead) or states exclusion conditions. Usage is implied rather than explicitly guided.

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

Deploy Server