delete_recursive

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

With no annotations, the description carries full responsibility for behavioral disclosure. It only states that deletion is recursive and warns to be careful, but omits critical details such as irreversibility, lack of confirmation prompt, potential to delete large directory trees, or any auth/permission requirements. This is insufficiently transparent for a destructive operation.

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 extremely concise, with two short sentences and front-loaded key information. Every word earns its place, delivering the essential behavior and a cautionary note without fluff.

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 having an output schema, the description is incomplete for a destructive tool. It lacks any mention of side effects, error handling, scope of deletion, or safety mechanisms. The warning 'Use with caution' is vague and does not provide actionable context. More detail is expected given the high-risk nature of recursive deletion.

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 already provides 100% coverage for the single parameter 'path', including its type and description. The description adds slight emphasis that the path can be a file or directory tree, but this is largely redundant. Baseline score of 3 is appropriate since schema already documents the parameter well.

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 with a specific verb ('delete') and resource ('file or directory tree'), and the adverb 'recursively' distinguishes it from sibling 'delete_path'. This is a clear and concise purpose statement.

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 a use case (recursive deletion) and warns 'Use with caution', but it does not explicitly contrast with sibling tools like 'delete_path' or specify when not to use it. The warning provides minimal context, but no clear directive on alternatives or conditions.

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