telegram-ads-mcp

Overview Schema Source Related Servers Discussions Admin

get_ad_stats

Read-onlyIdempotent

Retrieve time-bucketed ad stats including CTR, CPC, CPM, spend, and budget. Choose 5-minute buckets for the last 24 hours or daily buckets for lifetime performance.

Instructions

Time-bucketed stats plus CTR / CPC / actual CPM.

period=5min → last 24h in 5-minute buckets. period=day → full lifetime daily.
Success JSON echoes the request `period` (`5min`/`day`). `summary.period` is a
span label (`24h`/`Nd`), not the request arg.
`summary.spend` is already scaled (Gram on a TON cabinet); `spend_already_scaled`
is true; `spend_scale` stays for compatibility. Do not divide again.
`charts.budget` series/totals are scaled the same way (`values_already_scaled`).
Prefer `summary.spend`. No CSV tool — if you save a file, gitignored `reports/`.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ad_id`	Yes
`period`	No		5min

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Aug 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already indicate read-only, idempotent, non-destructive behavior, so the description earns full credit for going beyond them. It warns that summary.spend is already scaled and should not be divided again, explains summary.period is a span label rather than the request arg, and clarifies charts.budget scaling. These are exactly the behavioral traps an agent needs to avoid.

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?

The description is dense but every sentence earns its place. It front-loads the main purpose, then organizes behavioral caveats with clear references to JSON fields. The final note about no CSV tool prevents a likely mistaken workflow without adding noise.

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?

Despite being a read-only stats tool with an output schema, the description adds crucial context about period labels, spend scaling, chart scaling, and the preferred summary field. It gives an agent everything needed to call the tool correctly and interpret its response without falling into known pitfalls.

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?

With 0% schema description coverage, the description carries full responsibility for parameter semantics. It explains period=5min vs period=day behavior, the request echo, and the scaling-related fields. ad_id is not elaborated, but it is self-evident from the tool name and required 'Ad Id' schema title.

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 'Time-bucketed stats plus CTR / CPC / actual CPM', which clearly identifies the resource (ad stats) and the specific value-add over sibling tools like get_ad or get_ads. It also distinguishes the tool by emphasizing time bucketing and derived metrics.

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 makes the intended use clear: fetch time-bucketed statistics for an ad with period options. It does not explicitly name when-not-to-use alternatives like get_ad or get_ads, but the period semantics and metrics make the tool's role obvious.

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