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

Adds genuinely useful behavior beyond the annotations: the tool "opens nothing by itself" and returns screens/buttons/fields, which explains why readOnlyHint=true is correct and prevents an agent from assuming the workout is created. The note about the official API being partner-only also explains the rationale for the browser-based workflow. It stops short of describing the shape or length of the returned instructions.

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 critical qualifier ("opens nothing by itself") is buried mid-sentence inside a long semicolon-chained sentence, and phrases like "from ChatGPT, Claude or any AI agent" plus the dated API parenthetical are filler. The content is useful but the structure does not front-load the most decision-relevant fact.

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?

With no parameters and no output schema, the description carries the burden of explaining the return value, and it does so at a high level (screens, buttons, fields) plus the required follow-up tool family. Minor gap: it never states what the instructions assume about workout specifics supplied by the user.

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?

Zero parameters, so the baseline applies; there is nothing for the description to disambiguate. It does implicitly signal that no workout payload is passed here, which is the key semantic an agent needs to avoid inventing arguments.

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?

States a concrete verb and resource ("Add planned workout in the user's own TrainingPeaks account") and then clarifies the actual mechanic — it returns step-by-step instructions rather than performing the add. It does not explicitly differentiate itself from the sibling trainingpeaks_add_workout_from_library, which likely has a similar instruction-returning shape.

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?

Gives a clear follow-on path ("then do it with the cotlet_browser_* tools in the user's TrainingPeaks Cloud Browser"), which is real usage guidance. It does not say when to prefer this over trainingpeaks_add_workout_from_library or trainingpeaks_apply_training_plan, and says nothing about what workout details the agent must already have in context given the tool takes no arguments.

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