delete_objects_by_prefix

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

With no annotations, the description carries the full behavioral burden, and it only vaguely claims 'triple disaster-prevention circuit breaker guards' without naming thresholds, what is protected, or whether the guards can still allow mass deletion. It never says the operation is irreversible, what permissions are needed, or whether partially-matching trees are affected.

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?

It is a single short sentence, but brevity here comes from under-specification rather than economy: for a destructive recursive delete, the one clause about 'circuit breaker guards' is too abstract to earn its place, and nothing actionable is front-loaded.

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?

A destructive, recursive bulk-delete tool with no annotations, no output schema, and zero parameter documentation needs far more than one vague sentence. Missing are the confirm flag's meaning, irreversibility, scope of deletion, and failure/partial-success behavior.

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% across 3 parameters, and the description mentions none of them. It does not define prefix scoping semantics, whether bucket is optional/defaulted, or what setting confirm_recursive_delete=true actually authorizes, so it fails to compensate for the schema 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 conveys a recursive bulk cleanup of a virtual directory tree, which implies deletion by prefix, so the verb+resource is inferable. However, it never states the resource is S3 objects, and it does nothing to distinguish this from siblings like delete_object or delete_objects_batch, leaving the agent to guess which delete variant applies.

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 tool versus delete_object (single object) or delete_objects_batch (explicit key list), nor on when a recursive prefix delete is appropriate. The required confirm_recursive_delete flag's role is not explained either, so the agent has no routing rationale.

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