get_publication_stats

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

The description far exceeds what readOnlyHint=true provides: it discloses two authenticated reads, per-metric unit/window/source/missing-state reporting, undocumented summary windows, non-reconciliation between summary and summary-v2, 'a failed group is unavailable, never zero' failure semantics, missing ARR currency, and the meaning of 403/404 on both groups. This is exactly the kind of behavioral context an agent cannot derive from annotations. It aligns with, rather than contradicts, the readOnlyHint.

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?

Seven sentences, each carrying a distinct fact — purpose, auth mode, output format, two data caveats, failure semantics, currency gap, and error interpretation. No filler or restatement of schema fields, and the primary action is front-loaded in the first sentence.

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?

The output schema covers return shape, and annotations cover safety, so the description's job was to cover quirks — which it does thoroughly. Minor gaps remain: the 'trailing' anchor date is unspecified, and there is no guidance on when to prefer summary over summary-v2. These are small enough that the tool is still callable correctly without them.

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?

With 0% schema description coverage, the description carries the full burden for range_days. It adds the 'trailing' temporal semantics and states the range/default, but the bounds and default are already present in the input schema, and the anchor point for 'trailing' (from the current date?) is left unspecified. The compensation is adequate for a single simple parameter but not rich.

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 description opens with a specific verb and resource — 'Read dashboard summary and summary-v2 for a trailing range of 1–365 days (default 30)' — making the tool's scope precise. It doesn't explicitly name a sibling to differentiate from (e.g., get_post_analytics or get_growth_sources), but 'dashboard summary' clearly implies publication-level analytics rather than post-level, which is distinct enough for an agent to disambiguate.

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 through 'dashboard summary' — the agent can infer this is for publication-wide stats rather than per-post analytics — but there is no explicit when-to-use guidance, no exclusions, and no named alternatives despite 32 siblings. The 403/404 note is diagnostic, not routing guidance.

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