op3_new_vs_returning

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the baseline length affects results, the default is four times the window, and both baseline and window sizes are reported so the agent can judge reliability.

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 compact sentences, each earning its place: the first defines the operation, the second states the use case, and the third flags an important behavioral nuance. The critical caveat about baseline length is front-loaded within the third sentence and clearly explained.

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 tool with no output schema, the description does well by stating that both sizes are reported. It explains the default baseline multiplier and its effect. It could be more explicit about what 'first-time' and 'returning' mean operationally, but the schema and description together provide sufficient context for correct invocation.

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 100% description coverage and already explains identifier, start, end, bots, and baseline_multiplier. The description adds conceptual meaning about how the baseline comparison works and why baseline length matters, but it does not substantially extend parameter-level semantics 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?

The description states a specific verb ('Split') and resource ('a show's listeners in a window') and clearly differentiates the tool's purpose from siblings by focusing on first-time vs returning listeners. It also states the core question the tool answers, making its role distinct.

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 clear context for when to use this tool: when you want to know whether a show is reaching new listeners or serving the same audience. It does not explicitly name alternatives or exclusions, but the purpose framing provides enough guidance for an agent.

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