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

It corroborates and enriches destructiveHint=true: changes are irreversible, so confirm with the user first, and only the fields you pass change (partial update semantics that annotations do not convey). It also discloses refusal behavior—non-permitted fields rejected, overlapping cycles rejected, plain-text description rejected once HTML exists—which is exactly the kind of consequence context a mutating tool needs.

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?

Front-loaded with the destructive warning and the id/ownership lookup, then neatly grouped per event type so an agent can read only the relevant block. It is long, but 23 parameters at 0% schema coverage justify it; the creation-oriented quiz/question and date_end details are the main material that does not earn its place in an update tool.

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?

With an output schema present, return values need no explanation, and annotations plus description together cover safety, refusals, and field semantics thoroughly. The one substantive gap is the mismatch with the actual schema: the agent is told to send quiz_template/questions or creation-required date_end, which this schema does not accept, so a caller could plan a call that fails.

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 coverage is 0%, so the description must do all the work, and it largely does: id prefixes, athlete vs group vs neither ownership, per-type field lists with formats (HH:MM, YYYY-MM-DD), value sets (goal_type 'a'/'b', note_type, question types), and validation rules. The deduction is for mixing creation-only requirements into an update tool—`date_end` "required on creation", and `quiz_template`/`questions`, which are not in the schema at all and would be rejected by additionalProperties:false.

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 first sentence states a specific verb ("Change") and the four resource kinds, each named in the title as well (race, cycle, note, questionnaire). It is clearly separable from siblings create_planned_event, delete_event, and update_planned_training without opening any 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?

It states required preconditions (read the event with get_calendar(mode='planned') to obtain the pcmp_/pcyc_/pnot_/pqz_ handle; use list_sports, list_quiz_templates, list_metrics for IDs), gives the exact workflow for description edits, and names hard exclusions: questionnaire questions cannot be changed, an answered questionnaire cannot be changed at all, and other fields are refused.

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