Skip to main content
Glama
Upload-Post

Upload-Post

Official

Telegram Stars and payments

manage_telegram_payments
Destructive

Manage Telegram Stars, invoices, gifts, refunds, and subscriptions for a profile's bot, including balances, payment settings, and confirmed sends or refunds.

Instructions

Telegram Stars, invoices and gifts of the profile's own bot. Fields go in params with the API's names. Reads: stars_balance, star_transactions (offset, limit), get_payment_settings, unanswered_payments (limit: automatic payment answers that failed in the last 30 days), available_gifts, owned_gifts (user_id or chat_id, filters), unique_gift (name). send_invoice (title, description, payload, currency XTR for Stars or a provider currency with provider_token, prices [{label, amount}], photo_url, need_* fields, chat_id; it is posted in the chat) and create_invoice_link (same fields; subscription_period 2592000 makes a 30-day Stars subscription) ask other people to pay the bot. refund_star_payment (user_id, telegram_payment_charge_id; needs confirm, never retried) and edit_star_subscription (user_id, telegram_payment_charge_id, is_canceled; needs confirm). set_payment_settings: automatic pre-checkout answers (pre_checkout off|approve|reject, max_total_amount, allowed_payload_prefixes, error_message, shipping off|static, shipping_options, shipping_countries); they need the bot's updates on (manage_telegram_bot set_updates). send_gift (user_id or chat_id, gift_id, max_star_count, text, idempotency_key; needs confirm) and gift_premium (user_id, month_count 3|6|12, star_count 1000|1500|2500, idempotency_key; needs confirm) SPEND the bot's Stars. Needs the user's approval: call it first without confirmed to get a preview (nothing is sent), show the user exactly what will go out, and repeat the call with confirmed: true only after they approve.

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": {
      "action": "<action>",
      "user": "<user>"
    },
    "name": "manage_telegram_payments"
  }
}

Input Schema

NameRequiredDescriptionDefault
userYesUpload-Post profile name with Telegram connected.
actionYes
paramsNoOther API fields for this action, with the REST API's own names (snake_case) and shapes. See the description for each action's fields. Leave out what you do not want to change.
confirmNoThe API's own confirmation for deletions and other changes that cannot be undone. Set it to true only after the user has approved that exact change; without it those actions are refused and nothing changes.
confirmedNoSet to true only after the user has seen the preview this tool returns without it and approved it. Without it nothing is sent.

Output Schema

NameRequiredDescriptionDefault
resultNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.26.5

TDQS

A4.4/5.0
Behavior5/5

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

With destructiveHint=true and openWorldHint=true already declared, the description still adds substantial behavior: which actions spend Stars versus request payment, which require `confirm`, that refunds are never retried, that set_payment_settings depends on bot updates being enabled, that unanswered_payments covers failed automatic answers in the last 30 days, and that the unconfirmed call returns a preview with nothing sent. These are the exact facts an agent needs before invoking a destructive, irreversible tool.

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?

Prose is dense and front-loaded with scope, then organized by reads, payment requests, and spending actions. Nearly every clause carries information (field lists, enum values, prerequisites). It is a single long block rather than a formatted list, which makes scanning harder, but there is no filler.

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 14-action tool with a freeform params bag, the description covers scope, per-action fields, safety prerequisites, and the preview/confirm protocol; an output schema exists, so return values need not be described. Remaining gaps are minor, such as pagination behavior for star_transactions or what a failed refund/preview returns.

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?

The freeform `params` object would otherwise be opaque; the description enumerates per-action fields (stars_transactions offset/limit, prices [{label, amount}], subscription_period 2592000 for a 30-day renewal, gift_premium month_count 3|6|12 with star_count 1000|1500|2500, idempotency_key) and notes names follow the REST API. It also explains the difference between `confirm` and `confirmed`, which the schema alone states less precisely.

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?

The opening line plus the enumerated action list make the scope concrete: Stars, invoices and gifts for the profile's own bot. Each action is named with its fields, and the description separates reads (stars_balance, star_transactions, available_gifts), payment requests (send_invoice, create_invoice_link), and spend actions (send_gift, gift_premium). It never names a sibling tool, so cross-tool differentiation is left implicit, but the resource boundary ('the profile's own bot') 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 Guidelines4/5

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

The description gives explicit usage conditions inside the tool: refund_star_payment is 'never retried', set_payment_settings 'needs the bot's updates on', send_invoice 'is posted in the chat', and send_gift/gift_premium 'SPEND the bot's Stars'. It also spells out the two-step approval workflow (call without `confirmed` for a preview, then repeat with `confirmed: true` after approval). It stops short of pointing to any alternative sibling when this tool is the wrong choice.

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

Deploy Server

Other Tools