get_ads_stats

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

Beyond the readOnly/idempotent annotations it discloses several non-obvious behaviors: a hard 1000-interval cap, implicit paging when ad_ids is empty, that supplied ad_ids are used verbatim, that account_id falls back to TELEGRAM_ADS_ACCOUNT_ID then the token owner, and that totals are null when data is absent. It also instructs the agent to check complete and errors before trusting results, which is exactly the kind of caveat annotations cannot express.

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?

Purpose and time-range constraint are front-loaded in the first sentence, followed by short paragraphs each addressing one concern (paging, timeseries, return shape, defaults). No sentence is redundant or restates the schema, and the warning about complete/errors lands where an agent will read it before calling.

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?

An output schema exists, so return fields need not be fully documented, yet the description still summarizes the payload (rounded bounds, per-ad totals, counts, complete, errors) and flags null totals. The only real gap against a 6-parameter stats tool is the unexplained interval parameter and its interaction with the 1000-interval limit.

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?

With 0% schema description coverage the description carries the full burden and covers five of six parameters meaningfully: from/to semantics (half-open interval in Unix seconds), ad_ids empty-vs-supplied behavior, include_timeseries effect, and account_id defaulting chain. The interval parameter itself is never explained — neither the 300 vs 86400 enum values nor the 86400 default — so the largest remaining ambiguity is left unaddressed.

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?

The opening sentence states a specific verb and resource ("Get per-ad totals") plus the scope ([from_time, to_time), Unix seconds), which lets an agent separate it from get_account_stats and get_ads_by_id. It stops short of explicitly distinguishing it from the singular get_ad_stats sibling, leaving the plural/singular distinction to inference from the name.

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?

It gives operational conditions (period must not exceed 1000 intervals, empty ad_ids triggers automatic paging, include_timeseries adds interval rows) but never states when to choose this over get_ad_stats, get_account_stats, or get_account_report. The when-to-use decision is implied by output granularity rather than spelled out.

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