generate_analytics

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

No annotations are provided, so the description carries the full burden. It discloses that the call returns immediately, runs in the background, takes 2-5 minutes, and requires a completed session prerequisite. It also clarifies the non-blocking nature and the polling workflow, which is essential behavioral context for an async generation tool.

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 long but every section earns its place: purpose, prerequisite, timing, async behavior, polling instructions, and argument list. The use of emoji and bold headers (⚠️ PREREQUISITE, ⏱️) improves scannability, and the information is front-loaded with the core action.

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?

For a complex async generation tool with prerequisites and a polling loop, the description covers all necessary operational details: what to check first, how long to wait, how to check status, what to tell the user, and what to do after completion. An output schema exists, so return-value details are not required in the description.

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?

The input schema has one parameter (study_id) with 0% description coverage. The description's 'Args' line says 'study_id: The unique identifier of the study', which adds a label but is nearly tautological. It does not provide example values, format hints, or lookup guidance, so it only minimally compensates for the missing schema documentation.

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 'Trigger AI-powered analytics generation for a study', a specific verb+resource statement. It further enumerates all generated components (qualitative insights, quantitative data, Q&A analysis, summary, overall insights), clearly distinguishing this generation tool from sibling read tools like get_qualitative_insights and get_analytics_status.

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 gives explicit usage instructions: call get_participants first to verify completed sessions, call get_analytics_status first to avoid redundant generation, and after triggering, poll get_analytics_status up to 10 times with a provided fallback message. It also points to 'appropriate read tools' once generation completes, effectively contrasting with alternatives.

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