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

The annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, and the description is consistent with them by stating it 'opens nothing by itself'. It adds useful behavioral detail about the return value (screens, buttons, fields) rather than just a status. The closing paragraph on JobDiva's REST API, 759 paths and the absence of an official MCP server is contextual justification rather than behavior of this tool, so transparency gains are modest beyond what is already structured.

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 first sentence is front-loaded and useful, but the second is a long compound sentence stitched with a semicolon that mixes return format and the follow-up tool. The final JobDiva API paragraph is lengthy and largely tangential to invoking this tool correctly.

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?

There is no output schema and no parameters, so the description carries the burden, and it does cover the workflow handoff to cotlet_browser_*. It omits practical prerequisites an agent would need: whether the hotlist must already exist, whether multiple candidates can be added at once, and what the returned step-by-step content actually looks like beyond the phrase 'screens, buttons, fields'.

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 provides no surface for meaning to be added, so the baseline would normally be higher. However, for a tool whose concept requires identifying candidates, the description never explains how the agent conveys which candidates or which hotlist is meant — presumably via conversation before the browser step — leaving a real semantic gap the empty schema cannot cover.

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 verb and resource (adding candidates to a hotlist in the user's JobDiva account) and then clarifies the tool's real nature: it returns step-by-step instructions and 'opens nothing by itself'. That clarification is essential and distinguishes it from sibling write tools like jobdiva_create_submittal. The only weakness is that the opening phrase reads as the action itself, so the agent must read to the second clause to learn it is a guidance tool.

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 an explicit follow-on path: call this to get the steps, then execute them with the cotlet_browser_* tools in the user's JobDiva Cloud Browser. That is concrete when-and-how guidance. It stops short of exclusions, e.g. when to prefer jobdiva_add_candidate_note or the direct JobDiva API path rather than the browser flow.

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