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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered, and the description adds valuable behavior beyond that: the call returns retention data for rendering plus a compact summary for analysis, and it mandates a skill load before invocation. It does not discuss execution cost, latency, or result size limits for large time ranges, which is the remaining gap.

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?

Purpose and return shape are front-loaded in the first two sentences, with the operational rules and the skill prerequisite trailing. The third sentence is dense and slightly parsing-heavy ('A global filter or breakdown on a property or argument needs that column, with the same dataType, on both events'), but every clause carries actionable instruction rather than filler.

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 deeply nested 4-parameter query-builder with no output schema, the description covers purpose, return shape, the two-event model, filter placement rules, and a pointer to a skill that presumably supplies spec examples. An agent has enough to decide to call it and to know what to load before constructing the spec.

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 coverage is 75% and the nested schema already documents metrics as exactly two events and describes measurement/computeMode/retentionGroup. The description adds semantics the schema cannot express: how a filter or breakdown must reference the same column with the same dataType on both events, and that shared conditions belong in global filters rather than duplicated per event. That is genuine guidance beyond the structured fields.

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 concrete verb+resource ('Build and execute an ad-hoc retention analytics query') and then defines the retention semantics precisely: players who did a start event and returned to do a return event N days/weeks/months later. The word 'ad-hoc' implicitly separates it from the create/update_retention_query siblings, though it never names them explicitly.

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?

It gives real operating context: this is for ad-hoc retention analysis, a global filter or breakdown requires matching columns/dataTypes on both events, and a condition applying to both belongs in the global filters once. It also declares a hard prerequisite (loading the retention-queries skill first). It stops short of naming alternatives such as create_retention_query or run_insight_query, so the when-not case is left to inference.

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