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

Beyond the readOnly/destructive annotations, the description discloses an access precondition (leads require inbox access), a data-completeness caveat (by_post reach and views are null until fetched), and a domain rule that would otherwise look like a bug (one DM per person per post, so comments in can run ahead of people messaged). It also directs the reader to `notes` before comparing numbers. That is exactly the kind of interpretive context annotations cannot carry.

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?

The metric list is front-loaded and every clause is load-bearing — the DM-per-post caveat and the `notes` warning both prevent misreads of the numbers. It does, however, pack everything into long semicolon-chained sentences, and the split-dimension enumeration (by automation, keyword, post, account, campaign) is dense to parse on a first read.

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 six optional parameters, defaults on everything, and no output schema, the description has to explain the return surface itself — and it largely does, covering both the KPI metrics and each breakdown dimension. Gaps are minor: it does not say whether by_post/leads sections are paginated or how large the per-day arrays can get, and range_days granularity beyond the three listed values is only implied.

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 100%, so the schema already documents flow_id, range_days, include, campaign, profile_id and leads_limit — baseline 3. The description still adds meaning on top: it clarifies that include defaults to everything but leads, that leads are gated on both the include value and inbox access, and that the by_post row carries post-level reach/views. That is real added semantics rather than restatement.

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 clause names both the verb and the resource ("What automations did over the last 7, 30 or 90 days") and then enumerates the exact metrics returned — people messaged, DMs, comment replies, conversations, new contacts, emails captured, link clicks/click rate. That is far more specific than "get insights" and lets an agent pick it over sprkly_get_account_summary or sprkly_get_engagement_summary. It never names a sibling explicitly, which keeps it out of the top band.

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 context is implied rather than stated: the period comparison and per-day/split-by dimensions signal "use this for automation performance reporting," and the leads clause states a concrete precondition (include ["leads"] plus inbox access). But there is no explicit when-not or pointer to the adjacent analytics tools (sprkly_get_analytics, sprkly_get_automation_usage), so an agent must infer the boundary from the metric list alone.

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