telegram-ads-mcp

Overview Schema Source Related Servers Discussions Admin

launch_ad

Submit a Telegram ad for review by creating it on-hold, setting the budget, and sending targeting in one call. Returns the failed step, avoiding manual create, edit, and review calls.

Instructions

Create on_hold, add budget, submit for review. Does not activate.

Spends `budget` (default 1 Gram) and sends targeting to review. Not go-live.
Returns each step so you can see which one failed. Prefer this over calling
create_ad + edit_ad + send_target_to_review by hand.
Safe targeting subset vs create_ad: topics, exclude_*, locations, user_langs/user_topics.
Do not send langs together with specific channel IDs (platform Target invalid);
langs is dropped in that case. Full field set remains on create_ad.
confirm: required unless TG_ADS_WRITE_GATE=open.

Input Schema

TableJSON Schema

Name	Required	Default
`cpm`	Yes
`bots`	No
`text`	No
`langs`	No
`media`	No
`title`	Yes
`budget`	No	1
`topics`	No
`confirm`	No
`channels`	No
`countries`	No
`locations`	No
`user_langs`	No
`audience_id`	No
`promote_url`	Yes
`skip_review`	No
`target_type`	No	channels
`user_topics`	No
`daily_budget`	No	0
`exclude_crypto`	No
`exclude_topics`	No
`search_queries`	No
`exclude_politic`	No
`exclude_channels`	No
`exclude_user_topics`	No
`exclude_user_channels`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.3.0Sep 1, 2026

addedInput schema / properties / exclude_channels

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Exclude Channels"
+}

addedInput schema / properties / exclude_crypto

Added value: +{
+  "default": false,
+  "title": "Exclude Crypto",
+  "type": "boolean"
+}

addedInput schema / properties / exclude_politic

Added value: +{
+  "default": false,
+  "title": "Exclude Politic",
+  "type": "boolean"
+}

addedInput schema / properties / exclude_topics

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Exclude Topics"
+}

addedInput schema / properties / exclude_user_channels

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Exclude User Channels"
+}

addedInput schema / properties / exclude_user_topics

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Exclude User Topics"
+}

addedInput schema / properties / langs

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Langs"
+}

addedInput schema / properties / locations

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Locations"
+}

addedInput schema / properties / topics

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Topics"
+}

Changed1 schema field changedAug 30, 2026

addedInput schema / properties / confirm

Added value: +{
+  "default": false,
+  "title": "Confirm",
+  "type": "boolean"
+}

First observedv0.2.0Aug 29, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond annotations, the description discloses side effects (spends `budget`, default 1 Gram), lifecycle state (on_hold, not go-live), review submission, per-step failure reporting, an auth gate requirement (`confirm` required unless TG_ADS_WRITE_GATE=open), and a data-dropping behavior (`langs` dropped with specific channel IDs). This is rich, actionable behavioral context.

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?

The description is dense and front-loaded, with the core behavior in the first sentence followed by constraints and alternatives. There is minor redundancy ('Does not activate' / 'Not go-live', 'review' repeated), but every sentence still contributes useful operational information.

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?

Given the complexity of 26 parameters, three required fields, and a large sibling set, the description covers orchestration, side effects, constraints, and auth well, and the output schema covers return values. It does omit some material parameter behaviors like skip_review and daily_budget, but it explicitly routes agents needing the full field set to create_ad, making the common and safe invocation path complete enough.

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?

With 0% schema description coverage, the description compensates for key parameters: budget default, confirm requirement, the langs/channel conflict, and the safe targeting subset. However, it does not explain most of the 26 parameters (e.g., cpm, promote_url, target_type, daily_budget, search_queries, audience_id, skip_review), leaving the agent to infer meaning from names and enums. It is meaningful but incomplete compensation for a large parameter set.

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?

The description opens with 'Create on_hold, add budget, submit for review' — a concrete multi-step action with a clear resource and lifecycle state. It also distinguishes launch_ad from create_ad ('Safe targeting subset', 'Full field set remains on create_ad') and from the manual sequence, so an agent can tell exactly what this tool does.

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?

It explicitly says 'Prefer this over calling create_ad + edit_ad + send_target_to_review by hand,' naming the alternative workflow and the condition to choose this tool. It also points to create_ad when the full field set is needed and gives a concrete constraint about langs and channel IDs, which is clear when-to-use/when-not-to-use guidance.

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