tp_create_workout

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

No annotations are provided, so the description carries full burden. It does disclose one behavioral trait: 'Duration is auto-computed only from simplified structure when not provided,' which clarifies the effect of omitting duration_minutes. However, it does not mention permissions, idempotency, error behavior, or what the tool returns on success. The lack of an output schema means the agent cannot infer return semantics, leaving a significant transparency gap.

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 exactly two sentences. The first sentence front-loads the core purpose and key options, the second provides a critical behavioral caveat. There is no redundancy, fluff, or repetition of schema details. Every word earns its place.

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?

This is a complex creation tool with 15 parameters, nested objects, no annotations, and no output schema. The description is minimal and does not explain what the tool returns, how to verify success, or common failure modes. It also does not mention that tp_validate_structure exists as a companion for validating interval structures. Given the complexity, the description is under-equipped for a safe autonomous invocation.

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 93%, so the schema itself documents most parameters. The description adds value by clarifying the relationship between duration_minutes and structure: 'Duration is auto-computed only from simplified structure when not provided.' It also clarifies the two competing structure formats (simplified vs native structured_workout), which is not fully clear from schema alone. This extra context pushes it above the baseline of 3.

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 the tool's purpose: "Create a planned workout" – a specific verb with a specific resource. It also distinguishes this from sibling tools like tp_update_workout or tp_copy_workout by explicitly limiting it to creation, and mentions the two input modes (simplified structure or native TP payload). This is unambiguous and well-scoped.

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 implies usage for creating workouts but does not explicitly compare against alternatives like tp_update_workout for modifications or tp_validate_structure for pre-checking. There is no 'when not to use' guidance. The note about auto-computed duration gives some conditional guidance, but overall the when-to-use context is implicit rather than explicit.

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