get_candidates

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 does disclose several behavioral traits: calls are cheap, ALS candidates derive from the user's overall taste vector rather than a single seed, repeats default off, and not_interested titles stay excluded. But it omits the return format, pagination semantics, and any auth or rate-limit context. Decent disclosure, incomplete given zero annotation coverage.

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 a dense, unstructured block of roughly 130 words with no front-loading of purpose. It jumps erratically between requery strategy, seed resolution, limit behavior, score floors, the property route, ALS internals, allow_repeats, and detail level. Sentences are stacked without separation into a clear spec, making it hard to consume.

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?

Despite the length, the description is not complete for an 18-parameter tool with zero schema coverage and no annotations. The required 'audience' field is left unexplained, several filter parameters are ignored, and the relationship between parameters is implied rather than specified. The presence of an output schema partially offsets the need to document return values, but the parameter coverage gap is too large.

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 0%, so the description must explain the semantics of 18 parameters. It covers seed_titles, genre filters, exclude_title_ids, exclude_seed_title_ids, limit, min_vote_average, min_vote_count, allow_repeats, and detail — roughly half. The required parameter audience is never explained, and context, sort_by, year_to/year_from, media_type, keywords, and original_language are entirely undocumented. This is a major gap for a fully-unannotated 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 core function — that this tool returns candidate title IDs/records for the current ask — is never plainly stated. It is only inferred from phrases like 'Candidate calls are cheap' and 'Any returned title_id can be a seed.' The description is a wall of operational advice rather than a clear verb+resource specification, and it never distinguishes its output from the discover_titles sibling beyond a cryptic 'Property arguments add a discover route to the same pool.'

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?

There is substantial tactical guidance: when to requery with new seeds/genres/exclude_title_ids, to use resolve_title for user-named seeds, to use exclude_seed_title_ids for earlier positive seeds, and to set allow_repeats. However, this is intra-tool parameter guidance, not tool-selection guidance — it never explicitly says when to choose get_candidates versus discover_titles or the evidence tools. The guidance is present but muddled and scattered.

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