delete_movie

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

With no annotations, the description carries the burden and does well by disclosing the default non-destructive behavior ('Files are kept unless delete_files is set') and the re-add protection effect of add_import_exclusion. It does not mention irreversibility or permission requirements, but the core destructive behavior is transparent.

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?

Two sentences with no filler; the primary action is stated first and the two key options follow immediately. Every sentence 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?

For a low-complexity three-parameter delete operation, the description covers the main action, the destructive default nuance, and the import-list side effect. No output schema exists, so a bit more about the return/status could be added, but nothing blocks 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?

Schema coverage is 100%, so the baseline is 3, and the description adds value beyond the schema by explaining the default behavior ('Files are kept') and the consequence of each flag in practical terms. This helps an agent understand why it would set delete_files or add_import_exclusion.

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 uses a specific verb ('Remove') and a clear resource ('a movie from the library'), immediately distinguishing this from read, add, update, and file-focused sibling tools. The singular 'a movie' also separates it from the bulk delete_movies sibling.

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?

No guidance is given on when to choose delete_movie versus alternatives like delete_movies, delete_movie_files, or remove_queue_items. The conditional advice about delete_files and add_import_exclusion concerns parameters, not tool selection, so usage context is essentially absent.

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