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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which matches the description's "opens nothing by itself" and resolves the apparent write-verb paradox. Beyond that, the description adds genuinely useful context the annotations cannot: the return shape is procedural instructions ("screens, buttons, fields") and the official API path is unavailable because keys are support-gated. The only weakness is that it does not state what a caller should do if the instructions are incomplete or the account/browser is not set up.

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?

Three sentences, each doing distinct work: what is returned, which tools to chain next, and why the API is not an option. The dated verification note ("checked 23 Oct 2026") is the only slightly extraneous detail, and it is short enough not to hurt front-loading.

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 must carry the return-value burden, and it does by describing step-by-step screen/button/field instructions and pointing at the cotlet_browser_* tools that consume them. It falls short of complete only in omitting preconditions — that the Recruiterflow Cloud Browser must be connected and that the tool performs no action itself.

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, so the baseline is 4 and the schema carries no semantic burden. The description adds no param meaning because none is needed, though it also does not clarify that the returned instructions are generic rather than scoped to a specific candidate.

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 first clause, "Add candidate in the user's own Recruiterflow account from ChatGPT, Claude or any AI agent", reads as if the tool performs the add, and only the following clause ("Returns how to do it in Recruiterflow step by step... and opens nothing by itself") reveals the actual behavior: it returns instructions. The concrete verb/resource detail exists but is buried behind a misleading lead-in, and no sibling such as recruiterflow_add_candidate_to_job is named to disambiguate.

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 does give a downstream workflow hint — "then do it with the cotlet_browser_* tools in the user's Recruiterflow Cloud Browser" — which tells the agent where to go next. But there is no explicit when-to-use/when-not guidance, no prerequisites (account connected? browser session required?), and no contrast with the other recruiterflow_* candidate tools.

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