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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, yet the description adds substantive context beyond them: requires watchplus:read and current accepted membership, privacy and blocks are re-checked before returning, seen titles are excluded unless allow_rewatch, and predictions require fresh completed scores with missing coverage never implying agreement. Those are real operational caveats an agent cannot infer from the annotations.

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?

Front-loaded with the purpose and the prerequisite, then dense operational rules in a single tight paragraph with no filler. It is on the long side and packs several distinct rules together, but each sentence contributes a constraint or caveat rather than restating the name.

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 nested-request tool with an output schema, the description covers everything the agent needs: prerequisites, auth scope, exclusion defaults, prediction-freshness caveats, privacy re-checks, and how many candidates come back. Return-value formatting is correctly left to the output schema.

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 top-level schema exposes a single 'request' object, so the description carries weight in explaining semantics: focus, votes being lower priority without changing predictions, allow_rewatch, mood/reference inputs, and streaming filters. It does not mention limit, intent, qualities, member_ids, avoid_seed_ids or use_saved_services by name, though the nested schema documents those thoroughly.

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?

States a specific verb and resource: choosing what a group of accepted Watch+ members watching together might enjoy. The framing (group session, up to twelve candidates for the assistant to curate into two or three) makes it clearly distinct from recommend_for_me and recommend_titles without opening any schema.

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?

Gives concrete ordering guidance — resolve the group and people with get_my_watchplus_groups first — and conditions for focus=all_titles versus the default balanced fit. Also tells the agent not to demand a questionnaire and to use mood/references/streaming filters when known. It never explicitly states when to prefer recommend_for_me or recommend_titles over this tool, which keeps it below a 5.

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