clear_calendar_range

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

Annotations already mark destructiveHint=true, and the description adds meaningful detail: the destructive scope is 'every scheduled workout occurrence in a date range' and application is gated by confirm=DELETE. This goes beyond what the annotations provide and clearly warns the agent of the destructive nature.

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?

Two compact sentences with no filler. The core operation and scope are front-loaded, and the safety requirement follows immediately. Every word earns its place.

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?

Covers the operation, scope, and confirmation gate, but omits default behavior (apply=false means preview), what the preview output looks like, and any irreversibility warning beyond the annotations. Since there is no output schema, a bit more context would help an agent invoke it correctly.

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%, so the description must compensate. It links apply/confirm to the destructive action ('Applying requires confirm=DELETE') and startDate/endDate to the date range, but it does not clarify that apply defaults to false for preview mode or specify expected date formats.

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?

States a clear verb ('preview or remove') on a specific resource ('every scheduled workout occurrence in a date range'). The bulk scope distinguishes it from singular tools like remove_scheduled_workout, so an agent can tell what it does without opening the schema.

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?

Provides useful operational guidance: the tool can preview or remove, and applying requires confirm=DELETE. However, it does not explicitly name alternatives or exclusion conditions, such as using remove_scheduled_workout for a single occurrence, so an agent must infer when this tool is preferred.

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