Skip to main content
Glama
telegram-keyword-search

telegram-keyword-search

start_keyword_search

Launch a paid Telegram keyword search that finds relevant channels and returns a run_id for fetching matching posts; set keywords, date limits, and a spending cap.

Instructions

Start a Telegram keyword search that also FINDS the channels talking about each keyword, and return a run_id immediately. Step 1 of 2: then call get_keyword_results(run_id) to get the posts.

Starts the hosted Apify Actor "datalume/telegram-keyword-search-scraper" with your own
Apify account. Requires the APIFY_TOKEN environment variable. It is PAID: per matching
post plus a small fee per keyword when channels are found (current price:
https://apify.com/datalume/telegram-keyword-search-scraper ); non-matching posts and
unreadable channels are not charged. Starting a search spends money even if the results
are never fetched, so start one only when the user wants the posts. The run stops at
max_posts_per_keyword and at max_total_charge_usd. A run takes from a few seconds to
about two minutes (15 Nov 2026: 3 keywords, 259 posts from 19 channels in 2 min 15 s).

Args:
    keywords: words or phrases, e.g. ["Hyperliquid"]. Each keyword is searched separately.
    channels: optional channels that are always searched, e.g. ["durov"].
    discover_channels: find channels for each keyword with Google (site:t.me). Set false to search only `channels`.
    max_channels_per_keyword: found channels searched per keyword, 1-50.
    match_mode: "phrase" (exact phrase or #hashtag), "allWords" or "telegram" (everything Telegram returns).
    max_posts_per_keyword: stop a keyword after this many matching posts. Keep small to control cost.
    date_from: only posts since a date ("2026-11-01") or a period ("7 days", "24 hours"). Empty = any date.
    only_new_posts: return only posts published since the previous run of the same keyword in each channel.
    max_total_charge_usd: hard spending cap for this search, in USD.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "keywords": "<keywords>"
    },
    "name": "start_keyword_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
channelsNo
keywordsYes
date_fromNo
match_modeNophrase
only_new_postsNo
discover_channelsNo
max_total_charge_usdNo
max_posts_per_keywordNo
max_channels_per_keywordNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the billing model (paid per matching post plus a per-keyword fee when channels are found, non-matching posts and unreadable channels free), the APIFY_TOKEN requirement, the stop conditions (max_posts_per_keyword, max_total_charge_usd), and a concrete latency expectation (seconds to ~2 minutes with a benchmark). It even flags the key hazard an agent could otherwise miss: starting a run spends money even if results are never fetched.

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 identity and the step ordering in the first sentence, then cost, then per-argument notes - a sensible hierarchy. It is dense rather than padded, though the pricing parenthetical with an external URL is longer than needed and nudges the description toward verbosity.

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 nine-parameter, unannotated, no-output-schema launcher, this covers what an agent needs: prerequisites, cost and its cap, runtime, the returned run_id, and the mandatory follow-up call. Nothing material for a correct first invocation appears to be missing.

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 description coverage is 0%, so the Args block is the only documentation and it defines all nine parameters, including the three-valued match_mode semantics, date_from's two accepted forms ("2026-11-01" vs "7 days"), and the range for max_channels_per_keyword (1-50). It adds real meaning the schema titles alone would not convey, such as the cost-control intent of keeping max_posts_per_keyword small and only_new_posts being relative to the previous run of the same keyword.

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 ("Start a Telegram keyword search") plus the distinguishing behavior ("also FINDS the channels talking about each keyword") and the immediate return ("run_id"). It explicitly positions itself as "Step 1 of 2" against the sibling get_keyword_results, so an agent can pick the right entry point without opening a schema.

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

Usage Guidelines4/5

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

Gives clear sequencing ("then call get_keyword_results(run_id)") and a genuine when-not guard: "start one only when the user wants the posts," motivated by the cost warning. It also offers an in-tool alternative (discover_channels=false to search only `channels`). It stops short of contrasting itself with search_telegram_channels, so routing between the two top-level search tools is left implicit.

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