telegram-ads-mcp

Overview Schema Source Related Servers Discussions Admin

Ad stats

get_ad_stats

Read-onlyIdempotent

Retrieve views, clicks, CTR, CPC, CPM, and spend for a single Telegram ad over the last 24 hours or lifetime, with optional charts.

Instructions

Get views/clicks/CTR/CPC/CPM/spend for one ad. period=5min: last 24h; day: lifetime. summary.spend is already scaled (Gram); never divide. For many ads use get_ads. detail=full adds charts.

Input Schema

Name	Required	Default
`ad_id`	Yes
`detail`	No	summary
`period`	No	5min

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.6.0Oct 15, 2026

addedInput schema / properties / detail

Added value: +{
+  "default": "summary",
+  "enum": [
+    "summary",
+    "full",
+    "csv"
+  ],
+  "title": "Detail",
+  "type": "string"
+}

First observedv0.2.0Aug 29, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already cover readOnly/idempotent/non-destructive, so the safety profile is handled. The description adds real behavioral context beyond that: the spend scaling caveat ('already scaled (Gram); never divide') and that detail=full adds charts. It omits any auth or rate-limit notes.

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

Conciseness5/5

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

Three dense sentences with no filler; the returned metrics and the key scaling warning are front-loaded, and the sibling routing comes at the end.

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 an output schema present, return structure need not be described, yet the description still names the metrics and the spend-scaling gotcha. Combined with the period/detail semantics and sibling routing, an agent has everything needed to call it correctly.

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 description coverage is 0%, so the description carries the burden and largely does: it defines the non-obvious enum values for period (5min vs day) and explains detail=full. It leaves detail=csv and ad_id unexplained, but ad_id is self-evident.

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 (Get) plus the exact resource (stats for one ad) and enumerates the returned metrics (views/clicks/CTR/CPC/CPM/spend). It explicitly distinguishes itself from the sibling get_ads for the many-ad case.

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?

Routes the agent to the correct alternative: 'For many ads use `get_ads`.' It also defines when each period mode applies (5min = last 24h, day = lifetime), which is exactly the selection guidance an agent needs.

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