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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by stating 'opens nothing by itself' and describing the return payload as ordered steps with screens, buttons and fields, plus the fact that CoachingPortal has no public API. It stops short of describing the shape or length of the guidance, but the annotations carry much of the behavioral burden.

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 text is short but not front-loaded: the misleading imperative leads, and the clarifying 'returns how to do it' comes second. The clause 'from ChatGPT, Claude or any AI agent' is filler, and the closing 'CoachingPortal's official API: CoachingPortal publishes no public API.' is awkwardly duplicated phrasing.

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?

For a zero-parameter, read-only guide tool with no output schema, the description covers what it returns (ordered GUI steps), what it does not do (opens nothing), and the next step via the browser tools. What is missing is modest: no indication of scope of the returned steps or any prerequisite state for the user's account.

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 nothing for the description to disambiguate; the baseline for a zero-parameter schema applies. The description sensibly spends its words on the output and follow-up action instead of inventing parameter detail.

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 clause 'Set adherence weights in the user's own CoachingPortal account' implies a mutation, which the tool does not perform; the real purpose (returning step-by-step instructions for screens, buttons and fields) only appears in the second sentence. A reader must reconcile the title-like claim with the corrective detail before understanding what the call actually yields. It also gives no signal distinguishing it from similarly named siblings such as set_calculation_defaults or set_weight_tracking_policy.

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?

There is a genuine workflow instruction: call this to get the instructions, then execute them with the cotlet_browser_* tools in the user's CoachingPortal Cloud Browser. That tells the agent what to do next, but there is no guidance on when to use this versus the many other coachingportal_* settings tools, no prerequisites (e.g. user must be signed in), and the browser tool is referenced by wildcard rather than a named sibling.

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