shift_calendar_range

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-capable nature is known. The description adds the bulk-scope behavior (moving all workouts in a range) and preview modality via the apply parameter, but does not disclose side effects like conflict handling or reversibility. With annotations present, this is adequate but not rich.

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?

A single front-loaded sentence conveys the core action and scope without waste. It could add a brief note about the apply parameter or date format, but as it stands 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?

For a bulk-move tool with no output schema, low parameter coverage, and only minimal annotations, the one-sentence description leaves critical gaps: date format expectations, sign of days, inclusivity of endDate, conflict behavior, and preview response format. An agent would need to inspect sibling tool patterns or infer details to call this 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 only 25%, with startDate, endDate, and days lacking any schema descriptions. The description's phrase 'fixed number of days' gives minimal meaning to days, but it does not clarify date formats, sign conventions for days, inclusivity of endDate, or preview semantics beyond repeating apply's default. The description does not sufficiently compensate for the low schema coverage.

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 states a specific verb pair ('Preview or move') and a precise resource ('every scheduled workout in a date range by a fixed number of days'). This clearly differentiates it from singular operations like move_scheduled_workout and range operations like copy_calendar_range or clear_calendar_range.

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 the tool is for bulk date-range shifts, and the schema's apply parameter distinguishes preview vs. apply mode. However, it does not name alternatives or state when to prefer this over move_scheduled_workout, copy_calendar_range, or clear_calendar_range. Context exists but exclusions are absent.

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