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

Annotations already declare readOnlyHint/destructiveHint=false, so safety is covered; beyond that the description adds genuine behavioral context: cache-only reads, staleness handling, daily-mode row behavior, attribution limitations, and how metadata/result fields relate to conversions. It adds materially more than the annotations without contradicting them.

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?

Front-loads purpose and the cache workflow, then organizes required/date/example guidance into labeled sections. Density is high but each block earns its place; the example call is a strong addition. Minor redundancy around required/scope phrasing.

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?

For a 17-param tool with no output schema, the description covers the critical calling contract (required group_by/date/scope, correct date param names, attribution constraints) and even anticipates the connection_context requirement indirectly. Remaining gaps are the auxiliary params whose names are largely self-explanatory.

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 17 params, so the description must compensate, and it does for the high-value ones (group_by values, date_from/date_to with an explicit warning NOT to use start_date/end_date, the ad_account_id/product_id scope choice, and attribution rules). It leaves many params undocumented (management, consistency, require_complete_range, query_contract_version, search, page/page_size), so it only partially fills the gap.

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?

States a specific verb and resource ('Aggregated insight rows for the authenticated tenant, paginated and sortable') and clarifies the underlying source (tiktok_insights_daily) plus the legacy mapping nuance ('maps adset to TikTok's native ad group role'). This lets an agent distinguish it from siblings like insights_query_rows or insights_query_batch_overview.

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?

Explicitly states it is a cache-only read and routes the agent to insights_pull_insights when data is stale, which is real when-to-use guidance. It does not, however, distinguish itself from the other insight query siblings (rows/batch_overview/consistent), leaving that gap.

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