sonarr_delete_customformat

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

The description repeats the destructive nature already indicated by annotations (destructiveHint: true and readOnlyHint: false) but adds no new context beyond the annotation. It does not explain what gets destroyed, whether the deletion is permanent, or any downstream effects on related data. Since the description carries no additional behavioral information beyond the structured hint, the transparency is minimal.

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 concise and front-loaded with the primary action. The second sentence adds a redundant but impactful warning. While it could be considered filler given the annotation, it serves as a clear human-readable emphasis. Overall, no superfluous text beyond the repetition of the destructive hint, which is acceptable for such a simple tool.

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 simple single-ID delete operation, the description is minimally adequate. The annotations cover the destructive nature and the output schema exists, so return values don't need explanation. However, it lacks critical context such as the distinction from bulk deletion, what 'id' refers to, and any consequences of deletion (e.g., whether custom formats are removed from all series). The description does not fully compensate for the sparsely documented parameter.

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 input schema has one required integer parameter 'id' with no description, and the tool description does not mention it at all. With 0% schema description coverage, the description was expected to compensate by explaining that 'id' refers to the ID of the custom format to delete. It fails to do so, leaving the parameter meaning implied by the tool name alone.

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 the tool's function: 'Delete custom formats.' This is a specific verb (Delete) and resource (custom formats), making the purpose unambiguous. The destructive warning reinforces the action. The description distinguishes it from sibling tools like sonarr_get_customformat and sonarr_update_customformat, though it doesn't explicitly mention the single vs. bulk delete distinction.

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 provides no guidance on when to use this tool compared to alternatives. It does not mention that this tool deletes a single custom format by ID, nor does it point to sonarr_bulk_delete_customformat for multiple deletions. There is no mention of prerequisites, conditions, or exclusions. The usage context is only implied by the verb 'Delete', which is insufficient given the large number of sibling tools.

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