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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description's 'reads stored, does not live-fetch' is consistent with openWorldHint=false. It adds genuinely non-structured behavior: team members see only their assigned publication and no ARR or account-wide fields, while the owner sees ARR and Medium earnings. That authorization/field-visibility disclosure is the kind of context annotations cannot carry. It stops short of describing freshness/lag of the stored series.

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?

Three sentences that are dense but front-loaded: payload first, data-source caveat second, permission boundaries last. The long metric enumeration is load-bearing in an output-schema world but is on the edge of redundancy given the schema exists.

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 not be explained, yet the description still lists them; the more valuable coverage is the scope/permission statement (owner vs team, no ARR for team members), which nothing else provides. For a zero-required-param read tool this is close to complete, with only data-freshness/lag left unstated.

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%, with days, workspace, and publicationId all documented in the schema (including the 365 maximum and defaults), so the baseline is 3. The description's 'for a period' loosely maps to days and 'their assigned publication' reinforces publicationId, but it adds no syntax, format, or interaction detail 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?

States a specific verb and resource — 'Read the stored daily audience series' — and enumerates the exact metrics returned, which is far more specific than a restatement of the title. It does not name or differentiate itself from close siblings such as get_stats_insights, get_audience_overview, or get_platform_analytics, so an agent must infer the boundary from content rather than being told.

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?

'Reads what Narrareach has stored; it does not live-fetch Substack' implicitly tells the agent this is the cached/reporting path and nudges fresh-data needs toward refresh_* tools, but it never names an alternative or states a when-not condition. The permission scoping sentence is context, not selection guidance.

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