unschedule_workouts

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

With no annotations provided, the description carries full responsibility for disclosing side effects. It explicitly states that calendar entries are deleted, that this happens in a single call, and that workout templates are not affected. The IMPORTANT note about calendar-entry IDs versus workout IDs is a valuable behavioral caveat, though it omits details like authorization requirements or irreversibility.

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 well-structured and front-loaded: it states the action, the batch behavior, the template-preservation effect, and the critical ID caveat. There is minor redundancy in repeating 'calendar-entry ids from get_scheduled_workouts' in both the IMPORTANT note and the Args section, but no filler.

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 single-parameter bulk-removal tool, the description is complete: it explains what is removed, what is preserved, how to obtain valid IDs, and the key pitfall to avoid. An output schema exists, so return-value documentation is not required, and no prerequisites or alternative routing are essential for correct invocation.

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 only defines scheduled_workout_ids as an array of integers with no property description, but the description fully compensates by explaining that these are calendar-entry IDs from get_scheduled_workouts and explicitly warning that they are not workout IDs. This is exactly the disambiguation an agent needs to call the tool correctly.

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 uses a specific verb ('Remove') with a clear resource ('multiple scheduled workouts from the Garmin Connect calendar') and immediately clarifies that it deletes calendar entries in bulk. It also distinguishes itself from template deletion by noting the underlying workout templates are left intact, which separates it from sibling delete_workout/delete_workouts tools.

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 clearly implies batch usage ('Deletes multiple calendar entries in a single call') and gives important guidance about where the IDs come from (get_scheduled_workouts). It does not explicitly name the singular sibling unschedule_workout as the alternative for single entries, but the plural scope and ID-source guidance provide clear context.

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