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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this in behavioral terms by stating it "opens nothing by itself" and only returns screens/buttons/fields guidance. The note about API key procurement adds context that annotations cannot express. It leaves out whether the returned steps are generic or tailored to a specific candidate/job.

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?

Purpose comes first, then the mechanism, then the API caveat, which is a sensible ordering. The second sentence is a long run-on bundling return content, non-action, and the follow-up tool family, and the dated "checked 23 Oct 2026" note is slightly cluttered, but nothing is padding.

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 no parameters and no output schema, the description carries the full burden of explaining the return, and it does so only qualitatively ("screens, buttons, fields"). The significant gap is that a zero-parameter tool for adding a candidate to a job never explains how the specific candidate/job context is established, which is the first thing an agent will wonder.

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?

There are zero parameters, so the baseline of 4 applies; there is no parameter meaning for the description to add. The one thing it does not clarify is that the caller cannot pass a candidate or job identifier, which an agent used to other Recruiterflow tools might reasonably expect.

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 ("Add candidate to job") and immediately disambiguates that the tool only returns a step-by-step guide rather than performing the action. It does not name any sibling (e.g. recruiterflow_move_candidate_to_stage or recruiterflow_add_candidate) as the alternative, so the distinction from those write-style tools is left to inference.

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 workflow: call this to get the steps, then execute them with the cotlet_browser_* tools in the user's Recruiterflow Cloud Browser. It also explains why that path is needed (API keys are not self-serve and must be requested from Recruiterflow support), which is real routing guidance. It stops short of saying when not to use it or how it relates to the direct Recruiterflow action siblings.

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