Skip to main content
Glama
Telegram MCP

Telegram MCP

Check free public Telegram search quota

telegram_get_public_search_quota
Read-onlyIdempotent

Checks the linked account’s live free public-search quota for a proposed query without running a search, returning remaining daily uses, wait time, and whether the query costs a slot.

Instructions

Check the linked account's live free quota without performing a public search.

First search accessible account history. To offer a broader public-channel search, call this with the exact proposed query. Tell the user the returned remaining/daily free count, wait time if any, and whether is_current_query_free means this query uses no new slot. Do not assume 10 attempts or any fixed quota. Explain the scope includes channels they have not joined, then ask and WAIT for explicit consent. Only after their reply pass confirmation_token and user_confirmed=true to telegram_search_public_posts. Tokens expire in five minutes; a new query or changed quota requires a fresh check and consent. Never offer a paid search, Stars purchase, or automatic retry.

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": {
      "query": "<query>"
    },
    "name": "telegram_get_public_search_quota"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesTelegram text-search query, 2–200 characters; surrounding whitespace is trimmed. Use ordinary search text, not a local regex or SQL expression.

Output Schema

NameRequiredDescriptionDefault
quotaYes
reasonNo
statusYes
searched_scopeNopublic_channel_posts
normalized_queryYes
search_performedNo
stars_authorizedNo
confirmation_tokenNo
retry_after_secondsNo
free_search_availableYes
confirmation_expires_in_secondsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.14.0
    • addedInput schema / properties / query / description
      Added value: +"Telegram text-search query, 2–200 characters; surrounding whitespace is trimmed. Use ordinary search text, not a local regex or SQL expression."
  2. Addedv0.9.2

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds substantial behavior: five-minute token expiry, that a changed query or quota invalidates consent, that scope includes channels the user has not joined, and that no fixed 10-attempt quota should be assumed. The safety profile is consistent with readOnlyHint=true; only the return-shape narrative is thin, and an output schema exists.

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

Conciseness3/5

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

Front-loaded with the purpose, but the body is dense procedural prose that mixes tool description with orchestration policy, and the fragment "First search accessible account history" is ambiguous and reads as an incomplete instruction. Several consent/token sentences could be consolidated without losing meaning.

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 a one-parameter read tool with an output schema, the definition is nearly complete, and it helpfully names the returned concepts (remaining/daily free count, wait time, is_current_query_free) rather than leaving the agent to infer them. The only gap is the unclear account-history sentence, which leaves the pre-step slightly undefined.

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% and the query parameter is well documented there, but the description adds real meaning: the query must be the exact proposed one, and it determines whether is_current_query_free applies so the query consumes no new slot. That is semantic context the schema does not carry.

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: "Check the linked account's live free quota without performing a public search." The negation explicitly distinguishes it from the sibling telegram_search_public_posts, so an agent can tell the two apart without inspecting schemas.

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 when-to-use (call with the exact proposed query before a broader public search), a required sequencing with consent, duration of the token (five minutes), and explicit when-not-to ("Never offer a paid search, Stars purchase, or automatic retry"). The alternative path, telegram_search_public_posts with confirmation_token and user_confirmed=true, is named directly.

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