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

Annotations declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, and the description reinforces this by stating the tool 'opens nothing by itself', so an agent cannot mistake it for a mutation. It also characterizes the payload (step-by-step screens, buttons, fields), which is real value beyond the annotations. It does not say how long or in what format the guidance is returned, but with the safety profile already covered that is a minor 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 core scoping statement ('returns how to do it... opens nothing by itself') is front-loaded and earns its place, but the trailing sentence about Intervals.icu having a public REST API (with an odd future date) is irrelevant to selecting or invoking this tool. The opening 'from ChatGPT, Claude or any AI agent' is also marketing filler that delays the actual purpose.

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 zero parameters and no output schema, the description bears the burden of explaining what comes back, and it does so at a high level (screens, buttons, fields). However, it omits key operational context: with no parameters, the tool cannot know which activity is meant, and the description never explains how the target activity is identified or that a browser session must already exist before the cotlet_browser_* follow-up.

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 tool takes zero parameters and the schema is empty, so there is no parameter meaning to explain and the baseline of 4 applies. The description correctly implies a parameter-free, generic guidance call rather than implying any filtering 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?

The description eventually makes the real function explicit: it 'Returns how to do it in Intervals.icu step by step (screens, buttons, fields) and opens nothing by itself.' That is a clear verb+resource, but the opening clause 'Comment on an activity' and the title read like the tool performs the write, so the agent must read to the second clause to learn it is guidance-only. It names the cotlet_browser_* tools as the follow-up step but does not explicitly distinguish itself from cotlet_app_guide or the other intervals_icu siblings.

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 supplies a usable workflow: call this to get the steps, then perform them with cotlet_browser_* in the user's Intervals.icu Cloud Browser. That is implicit when-to-use guidance, but there are no exclusions (e.g. use intervals_icu_update_activity_notes_and_rpe if a direct API write is possible) and no stated prerequisites such as requiring an open browser session.

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