check_candidates

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

The description explains the main behavior: splitting IDs into three categories and optionally checking a Plex XML export. Since no annotations are provided, the description carries the burden, and it does convey that this is a checking/comparison operation. However, it does not disclose whether the operation is strictly read-only, what happens to uncategorized IDs, or how the Plex XML path is interpreted.

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 two short sentences with no filler. The main purpose is front-loaded, and the optional parameter explanation is separated cleanly. Every part of the description earns its place.

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?

With no output schema and no annotations, the description should explain enough to invoke the tool correctly. It gives the high-level behavior but omits the meaning of the required profile parameter and does not describe the output shape or category representation. This leaves important context missing for a new agent.

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 compensate. It explains plex_export_xml and references IMDb ids for the imdb_ids parameter, but the required profile parameter is not described at all. An agent is left guessing what profile means and how it relates to the queued state, which is a meaningful gap.

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 clearly states a specific verb and resource: 'Split a list of IMDb ids into already-queued, already-in-Plex, and new.' This makes the tool's function obvious and distinguishes it from queue-mutating siblings like add_to_queue or remove_from_queue. It does not explicitly name or contrast with related siblings like find_imdb_candidates, so it stops short of a perfect 5.

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 implies when the tool should be used: whenever you need to categorize IMDb IDs against existing queues and Plex data. It gives one concrete usage hint for the optional plex_export_xml parameter, explaining when to pass it, but it does not mention when to prefer or avoid this tool relative to its siblings.

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