growsurf_get_participant_analytics

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context beyond annotations: what the base response contains, what the 'email' include returns (sent/delivered/opened/clicked/bounced/spam), and what 'series' returns (per-period activity). It also clarifies default campaign targeting. No contradiction with annotations, and the added context is meaningful.

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 description is concise, about four sentences, and front-loaded with the core purpose before parameters. It is dense but not wasteful. Each sentence contributes either to the purpose, parameter guidance, or defaults. It could be slightly tightened, but it is well-structured for an 8-parameter tool.

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 are covered. The description covers all key usage aspects: what data is returned, how to optionally include email/series, how to bucket time, how to scope the window, and how to target a specific campaign. For a tool with 8 parameters and an output schema, the description is sufficiently complete for an agent to call it correctly without guessing.

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 63%, and the description compensates by explaining the purpose and effect of key parameters: include (with current values and 400 behavior), interval (day/week/month default), days (max 1825), startDate/endDate (Unix ms), and campaignId (defaults to GROWSURF_CAMPAIGN_ID). It also clarifies that participantId and participantEmail are two alternative identifiers. This adds significant meaning beyond the schema's bare properties.

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 clearly states the action ('Fetch analytics'), the resource ('one participant'), and the two identifiers (ID or email). It also lists the metric categories returned, which distinguishes it from participant profile tools (growsurf_get_participant) and campaign analytics (growsurf_get_campaign_analytics). This leaves no ambiguity about what the tool does.

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?

The description provides clear guidance on parameter usage: how to set include, interval, window scoping, and campaign targeting. However, it does not explicitly contrast this tool with sibling tools or state when an alternative should be chosen instead. The context implies its use case (per-participant analytics) but lacks explicit exclusions, so a 4 is appropriate.

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