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

Annotations already declare readOnly/closed-world/idempotent/non-destructive, but the description adds real context beyond them: the tool returns step-by-step UI instructions (screens, buttons, fields) and performs no side effect, and it names the companion tool family needed to actually execute the change. That resolves a naming ambiguity the annotations alone could not. The trailing 'official API: Yes ... (checked 6 Nov 2026)' sentence adds no behavioral information and undercuts an otherwise strong disclosure.

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 core fact (returns guidance, executes nothing, pair with cotlet_browser_*) is buried mid-sentence behind a misleading lead clause. Padding such as 'from ChatGPT, Claude or any AI agent' and a marketing-style API-availability sentence with a date stamp do not earn their place. Front-loading is poor.

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?

It correctly states what the tool returns, which matters since there is no output schema, and it points to the execution tooling. But it omits how the target planned workout is identified and what happens if no such workout exists, leaving real gaps for a zero-param tool with a mutating-sounding name.

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?

With zero parameters the schema baseline is high, but this is exactly the case where the description should explain how the target workout and the new values are conveyed (via conversation context presumably) — it says nothing. An agent calling a tool named 'update planned workout' with an empty object gets no explanation of how the request is specified.

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 opening phrase 'Update planned workout' is contradicted two sentences later by 'returns how to do it step by step ... and opens nothing by itself', so the real function (returning instructions, not mutating) only becomes clear after reading the whole text. It also does not distinguish itself from the sibling intervals_icu_create_planned_workout beyond the update/create verb. An agent can eventually work out what it does, but the framing misdirects.

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 a follow-up workflow ('then do it with the cotlet_browser_* tools in the user's Intervals.icu Cloud Browser'), which is genuine usage guidance. However, it never says when to choose this over create_planned_workout or the browser tools directly, and gives no prerequisites (e.g. that a planned workout must already exist and how the agent knows which one).

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