Skip to main content
Glama

set_watched_groups

DestructiveIdempotent

Replace a telegram_mtproto userbot's watched-groups list — the chats it monitors. Requires the manage_settings permission. SET semantics: send the COMPLETE desired list every time (call list_watched_groups first and include existing entries you want to keep — omitting one removes it). Each entry needs a chatId (e.g. "-100…") or a public username/t.me link, and it must be a group or channel the account has JOINED. Every entry is checked against the account before saving: a username no chat has, a chat the account is not in, or a person/bot refuses the WHOLE list with MTPROTO_WATCHED_INVALID naming each bad row (nothing is saved) — fix the spelling or join the chat with the account, then resend. Confirmed rows come back with checkStatus "ok" and their chat id and title filled in; when the userbot cannot answer (offline) the list is saved and rows come back "unverified". The running userbot picks the change up within a few minutes, no restart. An empty list means "watch every joined chat" — NOT "watch nothing".

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": {
      "groups": "<groups>"
    },
    "name": "set_watched_groups"
  }
}

Input Schema

NameRequiredDescriptionDefault
botIdNoThe telegram_mtproto bot. Omit when the application has exactly one userbot.
groupsYesThe complete replacement list. Empty array = watch every joined chat.
applicationIdNoApplication (workspace) id. Optional: an application-scoped key (app_...) defaults to its own application, but a personal key (usr_...) has no default and omitting it fails with MCP_APPLICATION_REQUIRED. Call list_applications to get the id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / groups / items / properties / mode / description
      Previous value: -"\"joined\" (default) = passive updates for a chat the account is in; \"public_peek\" = poll a public chat without joining (max 10)."New value: +"Always \"joined\" (the default, may be omitted): a chat the account is a member of. No other mode exists."
    • changedInput schema / properties / groups / items / properties / mode / enum
      Previous value: -[
      -  "joined",
      -  "public_peek"
      -]New value: +[
      +  "joined"
      +]
    • changedInput schema / properties / groups / items / properties / username / description
      Previous value: -"Public @username or t.me link. Required for public_peek entries."New value: +"Public @username or t.me link of a chat the account is in. Supply this or chatId."
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) by disclosing the manage_settings permission gate, atomic all-or-nothing validation, the MTPROTO_WATCHED_INVALID error code with per-row naming, and the degraded "unverified" path when the userbot is offline. It also states propagation timing (picked up within a few minutes, no restart), which an agent cannot infer from structured fields. No contradiction with the destructive/idempotent hints.

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 verb and SET semantics before the validation and error details, so the critical behavior is read first. It is a single dense block with a few overlapping sentences (validation refusal stated twice in variant forms), but nearly every sentence carries operational value.

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?

With no output schema available, the description supplies the return contract itself — checkStatus "ok" with populated chat id and title, or "unverified" when offline — plus failure modes and side effects. Nothing an agent needs to call this destructive, idempotent write correctly appears to be missing.

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 already 100%, so the per-field meanings (chatId, username, title, mode) are documented structurally. The description still adds load-bearing semantics the schema cannot convey cheaply: that the list is a full replacement rather than a merge, that entries must be joined chats, and that empty means watch-all. Slightly redundant in restating the chatId/username alternatives.

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 ("Replace a telegram_mtproto userbot's watched-groups list — the chats it monitors") and is immediately distinguishable from the sibling list_watched_groups, which it explicitly references. The scope of the replacement is unambiguous.

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 and how-to-use guidance: SET semantics, the instruction to call list_watched_groups first and resend existing entries, the requirement that chats be joined, and the remedy path (fix spelling or join the chat, then resend). It also pre-empts the most likely misuse by clarifying that an empty array means "watch every joined chat," not "watch nothing."

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.