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

Annotations already declare readOnly, idempotent, non-destructive, so the bar is lower; the description still adds real substance beyond them — default 30-day window capped at 93 days, result totals broken out per currency, daily per-ad rows summed per ad, and contentId being null when the ad is unlinked with an `unlinked` count. What is missing is any note on result volume or whether a wide range truncates.

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-loaded with the metric set and scope, then the level variant, then the endpoint wrapper — a logical order with no filler sentences. It is dense but nearly every clause carries information; the parenthetical API reference at the end is the only low-value element.

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 read-only reporting tool with no output schema and only four optional parameters, the definition covers the response shape well enough (per-currency totals, per-ad metric list, contentId and unlinked counts). The remaining gap is routing guidance versus the other analytics siblings, which is a usage concern the description leaves open.

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 coverage is 75% and the schema itself documents to, from, and brandId thoroughly, including the 403 case. The description's contribution is explaining what level: "ad" actually changes (daily per-ad rows, CTR, video views, contentId lineage), which is meaningful since the enum carries no description in the schema, but the other parameters get nothing beyond the schema.

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 description names the exact metric set (impressions, clicks, spend, link clicks, leads), the grouping (per campaign), and the date scope, plus the alternate per-ad mode. It does not say how this differs from the sibling tools query_insights or get_analytics, which is the only missing piece for a top score.

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: it tells the caller to pass level: "ad" for per-ad results and supplies the default and maximum date window, which effectively defines the valid call context. But it never says when to prefer this over query_insights, ads_campaigns_list, or ads_account_spend_limit_set, and there are no explicit exclusions.

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