render_garmin

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

With no annotations provided, the description takes on full disclosure. It reveals that the returned payload is ready for upload_workout unchanged, explains how power targets and percentages are resolved (power.between, FTP), and details the RepeatGroupDTO endCondition handling to avoid corruption. It also clarifies the tool's non-upload behavior.

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 concise and front-loaded: the first sentence states the primary purpose, followed by two focused paragraphs covering conversion details and usage caveats. Each sentence adds functional information without redundancy.

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 covers the core behavior, output readiness, transformation rules, non-upload caveat with an alternative, and the optional out_path. Since an output schema exists, return-value documentation is not needed. It stops short of documenting error cases or prerequisites, but the overall context is sufficient for a complex rendering tool.

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 provides only parameter names and types, with no descriptions (coverage 0%). The description compensates by explaining that out_path writes JSON to disk and by describing how the spec's FTP and percentage targets are interpreted. However, the spec object's full structure is not spelled out, leaving some ambiguity.

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, 'Render a workout spec to a Garmin Connect workout payload,' gives a specific verb and resource. The name render_garmin distinguishes it from sibling render_zwo (Zwift rendering), and the description further clarifies it produces a payload for Garmin Connect, not an upload.

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 includes an explicit exclusion: 'This server does not upload,' and points to the garmin-upload skill as the alternative that uploads and verifies. While it doesn't explicitly contrast with render_zwo, the distinct format and the clear purpose make selection clear.

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