Create Hevy Routine Folder

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds genuinely new behavior: the default is a preview, and Hevy inserts the folder before existing folders, which is ordering side-effect information the agent cannot get from annotations. It is consistent with the annotations, since the tool can write when dry_run is false.

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 tight sentences with no filler; the mode and the ordering side effect come first, followed by the safety condition. Every clause carries operational 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?

For a two-parameter create tool with an output schema (so return values need no explanation) and supporting annotations, the description covers mode, side effects, and a write-safety rule. The only real gap is the shape of the required folder object.

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 has to carry all parameter meaning. It does well on dry_run (false means write, default behavior is preview), but says nothing about the required 'folder' nested object beyond the tool's own framing, leaving the agent to read the schema to learn it needs a non-empty title.

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 names a specific verb and resource (create a routine folder) and discloses the dual preview/write mode, so the agent knows exactly what operation is available. It does not explicitly contrast itself with siblings like list_hevy_routine_folders or create_hevy_routine, though the names plus 'routine folder' make the distinction reasonably clear.

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 gives an explicit conditional for the mutating path: 'Set dry_run=false to write; only execute a write when the user has requested it.' That is a real when-to-act rule rather than vague context. It stops short of saying when a preview is preferable or what to do instead if the folder already exists.

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