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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, and the description explains the surprising part: despite the 'log' verb, the tool opens nothing itself and only returns instructions. That resolves what would otherwise look like a contradiction, and the no-public-API note adds useful context. It leaves some gaps, such as whether a Cloud Browser session must already exist and what happens if it does not.

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 information is front-loaded as purpose, return value, non-action, then next step, which is an effective order. Some wording is filler, notably 'from ChatGPT, Claude or any AI agent', and the closing line 'CoachingPortal's official API: CoachingPortal publishes no public API' is a redundant fragment.

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 carries the return-value burden and does so by specifying step-by-step screen/button/field instructions. Combined with the existing annotations, an agent has enough to decide to call it and to know what to do next. A brief note on Cloud Browser session prerequisites would make it complete.

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 no parameters, so there is no schema meaning to supplement and the baseline applies. The description adds a meaningful implicit scoping note by referring to 'the user's own CoachingPortal account' and 'today', though neither is expressed as an input.

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 states a specific resource and outcome: it returns step-by-step instructions (screens, buttons, fields) for logging a recipe today in the user's own CoachingPortal account. Crucially it disambiguates the verb 'log' by clarifying that the tool itself does not perform the action, distinguishing it from write-style siblings such as manage_personal_food_log. It stops short of naming a sibling alternative, so it is clear but not fully differentiated.

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 concrete follow-up path: take the returned steps and execute them with the cotlet_browser_* tools in the CoachingPortal Cloud Browser. It also explains why a browser route is needed at all (no public API). What is missing is explicit when-not guidance, e.g. when to prefer a direct logging sibling over the browser walkthrough.

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