delete_episodefile_bulk

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

Annotations indicate destructiveHint=true and idempotentHint=true, but the description does not specify the payload format for bulk deletion or clarify whether partial failures are possible. The destructive nature is clear from the name, but the description adds no detail about side effects or idempotency.

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 very short, with just two sentences. The HTTP endpoint is front-loaded)SkipDeleted. The brevity is appropriate for the simplicity, though the lack of critical detail reduces the score slightly.

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?

There is an output schema, so return value details are not needed. However, for a bulk delete operation, the agent needs to know exactly what the body should contain, e.g., an array of IDs. The description's advice to consult the GET or schema endpoint is a workaround, not a complete spec, leaving the description incomplete for effective 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 schema shows a single 'body' parameter with no type constraints, and the description merely says 'body: Request payload' without the required structure. Since schema coverage is 0%, the description fails to compensate by specifying that the body should contain an array of episode file IDs or similar.

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 it deletes EpisodeFile resources via the bulk endpoint. It includes the HTTP method and path, which helps distinguish it from single-delete and update operations. However, it does not explicitly differentiate from delete_episodefile_by_id, so it is not a 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?

There is no guidance on when to use this bulk delete versus the single delete, nor any discussion of the body structure needed for bulk deletion (e.g., an array of IDs). The hint to read the GET or schema endpoint is generic and not specific to this tool.

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