Get brand analytics

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: the window is clamped to plan history with maxDays reported, unavailable provider metrics are null rather than zero, and coverage spans both Markaestro and natively discovered posts via coverage.bySource. These are meaningful operational caveats not present in the annotations.

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 the purpose and scope before the enumeration, and every sentence carries information. It is dense and the first sentence is long, but nothing is padding and the caveats (clamping, null metrics) are isolated at the end.

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 takes on the burden of explaining return contents and does so thoroughly (the list of rollups, series, insights, and coverage). Edge cases like history clamping and null-vs-zero metrics are covered; only pagination/response sizing is unaddressed, which is minor for an aggregate analytics read.

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 100%, so the schema already documents every parameter (tz, days, since/until, source, channel, productId). The description adds minor scope nuance around productId/all-brands behavior, but essentially restates what the schema encodes; baseline 3 is correct here.

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?

Names a specific resource (brand performance analytics) and fully enumerates what the response contains (totals with prior-period deltas, per-channel rollups, daily series, heatmap, insights, coverage). It also states the scope resolution (connection's brand vs all-brands workspace vs productId brand), which lets an agent distinguish it from sibling analytics tools.

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?

Provides one usage cue — 'Read this before recommending what, when, or where to post' — which implies a decision-support context. However, it never distinguishes itself from close siblings like get_evergreen_analytics, list_post_analytics, get_post_analytics_history, or suggest_post_times, leaving the agent to infer which analytics tool to pick.

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