rm_delete_holiday

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

With destructiveHint and readOnlyHint already in annotations, the description appropriately adds the non-obvious guardrail that confirm must be true for deletion to occur. It does not go into irreversibility or cascading effects, but for a two-parameter delete operation the core destructive behavior is disclosed.

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?

One compact sentence with a parenthetical carries the action, the destructive warning, and the required guard condition. There is no filler or redundancy, and the critical usage condition is placed immediately after the verb.

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 two-parameter delete with an output schema and covering annotations, the description plus the schema gives an agent everything necessary to call it correctly: the target, the safety warning, and the confirmation requirement. It is slightly lean on broader consequences, but nothing essential for invocation is missing.

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 description adds meaning to the confirm parameter by explicitly stating it must be true, which is not inferable from its default of false. However, it adds nothing about holiday_id beyond its self-evident name, and with 0% schema description coverage the description only partially compensates for the missing parameter documentation.

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 opens with a specific verb and object, 'Delete a holiday', which unambiguously identifies the target resource and action. It also marks the operation as Destructive, reinforcing the semantic and distinguishing it from non-destructive holiday tools such as rm_get_holiday and rm_update_holiday.

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 statement 'requires confirm=True' gives a concrete precondition for invoking the tool, which is essential because the schema defaults confirm to false. It clearly positions the tool as the delete operation for holidays, though it does not explicitly enumerate alternatives or say when not to use it.

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