ads_telegram_ads_api_sync

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

With zero annotations the description carries the full burden, and it does deliver one important behavioral fact the schema cannot: the read direction is one-way and nothing is written back to Telegram. It omits what the local write actually overwrites/upserts, whether the operation is idempotent or re-runnable for the same date range, and any rate-limit or auth requirements — all material for an 8-parameter sync tool.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the critical scope disclaimer. No filler, no restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Eight undocumented parameters, no annotations, and no output schema means the description is doing almost none of the explanatory work. For a sync tool an agent needs to know date-range semantics, what the local model ends up containing, and whether re-runs are safe — none of which are covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 8 parameters, and the description compensates for none of them: no explanation of from/to bounds, the stats_period enum ('5min' vs 'day'), max_ads capping, include_stats toggling, or whether account_id/project_id are optional-but-needed in practice. The agent must guess the reporting semantics entirely from bare property names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: reads Telegram Ads API metrics and persists them into the local SQLite campaign model. The sentence 'This never writes to Telegram Ads' positively distinguishes it from the write siblings (ads_telegram_ads_api_set_ad_paused, ads_telegram_ads_api_create_ad), but it never names the closely related ads_telegram_ads_api_report or ads_telegram_ads_sync, so the read-vs-persist distinction among the read tools remains inferential.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Usage is implied rather than stated: 'persist them into the same local SQLite campaign model' suggests this is the backfill/refresh path for the local model. There is no explicit when-to-use versus ads_telegram_ads_api_report, no mention of needed credentials or of run cadence, and no exclusion guidance other than 'never writes to Telegram Ads'.

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