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

Annotations already establish readOnly/idempotent/non-destructive, yet the description adds substantial non-obvious behavior: fixed 20-record partial pages, oldest-first history that excludes later completed Scans from continuation, restart-on-repair semantics, and that percentage denominators retain complete evidence. These are exactly the operational traits structured fields cannot convey.

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?

It is telegraphic and dense, with defaults and the core metric/groupBy framing front-loaded before pagination and edge-case rules. Nearly every clause carries distinct information, though the packed one-fact-per-sentence style could be slightly better grouped.

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 values need no explanation, and the description covers the remaining gaps for an 18-parameter paginated series: defaults, pagination contract, filter-continuation rules, date semantics (UTC calendar days vs completedAt), and subjectContext nullability for legacy scans.

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 94%, so the schema already documents most parameters and baseline is 3. The description goes beyond it with cross-parameter constraints the schema cannot express: brand-grouped timelines use brand/competitorId and reject brandId, Topics require an explicit brandId to keep the entity fixed, and platform aliases combine weighted evidence.

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 'One metric over time' states a specific resource and shape (a time series of a single metric, selected via the metric argument), which separates it from snapshot-style siblings such as get_visibility_overview. It never names or contrasts an alternative sibling explicitly, so it falls short of the 5 bar for sibling differentiation.

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?

The description gives real operating rules: follow nextCursor with unchanged filters, restart after metadata/evidence edits, and that groupBy=brand rejects brandId. However, it never says when to pick this tool over get_visibility_overview or get_prompt_result_trends, so the when-to-use-vs-alternatives dimension is only implied.

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