Create zones

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

Beyond the annotations (which only indicate it's not read-only), the description discloses that bands are computed by TrainingPeaks' calculator, and reveals two specific behavior outcomes: ZONES_EXIST if already present and TEST_BASED_METHOD for unsupported methods. This concrete behavioral context is highly valuable for an agent deciding whether to call this tool.

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 compact and well-structured: two sentences deliver the primary purpose first, then the exceptions and redirects. Every clause earns its place, with no filler or redundant rephrasing of the tool name.

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?

Given the tool's complexity (9 parameters, no output schema), the description covers purpose, use conditions, and unsupported cases effectively. It even mentions two return statuses. However, it does not outline the success response shape or fully explain how parameters interrelate for different sports, leaving a slight gap in an otherwise thorough description.

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 moderate (56%), and the description adds some context by explaining that calculation_method determines how bands are computed and pointing to tp_get_zone_methods. However, it does not clarify cross-parameter dependencies (e.g., which parameters apply to power vs. heartrate vs. speed), so the agent may still be uncertain about required inputs for each metric.

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 clearly states 'Create a NEW per-sport zone set' with a specific verb and resource, and immediately distinguishes itself from sibling tools by naming tp_update_ftp/hr_zones/speed_zones for modifying existing sets. This makes the tool's unique role unmistakable.

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 explicitly says to use this tool only when the athlete has no existing set for that sport, and points to the update tools for existing sets. It also excludes test-derived methods (Distance/Time) from being created here, directing to the TP UI instead. This is clear when-to-use and when-not-to-use guidance.

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