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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations: missing buckets are zero-filled, scans include secondary_value, and the call does not spend credits.

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 and compact: the core purpose comes first, followed by metric semantics and two important behavioral details. Each sentence earns its place.

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?

With no output schema, the description still explains enough about the returned series: it is continuous due to zero-filled buckets, and scans include secondary_value. It does not describe response envelope or date-label format, but is otherwise complete for correct invocation.

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?

The description adds meaning beyond the schema by defining scans as QR/link views and explaining secondary_value for that metric. It restates the metric and day/week bucket choices, but does not add guidance for the date-range parameters.

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: get an account-wide mail analytics time series for a single metric, bucketed by day or week. The purpose is clear, but it does not explicitly contrast with sibling tools such as the mail analytics summary or campaign analytics.

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: use this when you need a metric charted over time. However, it gives no explicit when-to-use versus summary or campaign-analytics alternatives, and no exclusions or prerequisites.

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