update_garmin_workout

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

The description discloses several behavioral traits beyond the annotations: this is a full overwrite, fields omitted are dropped, the workout id is preserved, and invalid sessions produce an authentication-prompt message rather than an exception. These details are not conveyed by the annotations or schema. There is no contradiction with the idempotentHInt.

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?

Three sentences, no filler. The core action and overwrite semantics are front-loaded, followed by the critical warning and the auth-failure behavior. Every sentence carries useful information.

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?

The description is strong given the rich input schema and workflow guidance. It covers overwrite semantics, the need to fetch first, and authentication failure behavior. Minor gaps remain: it does not describe what a successful update returns, and it does not say what happens if the workoutId does not exist. These are not fatal, but they leave some ambiguity for an agent without an output schema.

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 100%, so the schema already documents all parameters thoroughly. The description adds the important semantic that omitted fields are dropped, which affects how optional parameters like poolLength and poolLengthUnit are interpreted. Otherwise it does not add much per-parameter meaning beyond the schema's own descriptions, so the baseline 3 applies.

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 and resource: 'Replace the entire contents ... of an existing workout, identified by workoutId, keeping its id.' It clearly distinguishes this from create_garmin_workout by emphasizing full overwrite on an existing workout and explicitly says it is not a partial patch. An agent can immediately tell this tool from its siblings 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 clear context and a concrete prerequisite: 'Call get_garmin_workout first to see the current contents before changing them.' It also warns that omitted fields are dropped, telling the agent to include all desired fields. It does not explicitly name create_garmin_workout as the alternative for new workouts, but the 'existing workout' language makes the intended use apparent.

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