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

Annotations already establish readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the return value is step-by-step UI instructions rather than data, and no browser session is opened as a side effect. The trailing note about the REST API v8 and the required OAuth2 client setup explains why browser automation is the fallback path, which is useful context, though the 'checked 23 Oct 2026' stamp is odd filler.

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 most important fact — that this tool returns instructions and performs no action — is buried mid-sentence behind a marketing-style opener about ChatGPT and Claude. The closing REST API/OAuth2 sentence is defensible as justification for the browser fallback but is longer than it needs to be and carries an irrelevant verification date. Tightening the opener and front-loading the 'returns steps, does nothing' clause would materially improve it.

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, no output schema and a rich annotation set, the remaining burden is explaining what comes back and what the agent should do next — and the description does both (step-by-step screens/buttons/fields, then drive cotlet_browser_*). The only gap is how the specific lead to convert is determined, which an agent may need to resolve elsewhere.

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 schema has nothing to document and the baseline of 4 applies. The description adds no parameter detail, which is appropriate here, but it also omits which lead is being converted — presumably resolved from conversational context — leaving a small ambiguity about how the target lead is identified.

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 definition names a specific CRM resource (lead conversion) and then explicitly redefines the actual function: it 'Returns how to do it in SuiteCRM step by step (screens, buttons, fields) and opens nothing by itself.' That clarification lets an agent distinguish it from the sibling write tools like suitecrm_create_lead. The opening phrase 'Convert lead in the user's own SuiteCRM account from ChatGPT, Claude or any AI agent' reads like the tool performs the conversion, which muddies the first impression before the correction arrives.

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?

The description gives a clear routing rule: call this first for guidance, then execute with the cotlet_browser_* tools in the SuiteCRM Cloud Browser. It also states a negative condition ('opens nothing by itself'), preventing an agent from expecting a mutation. It does not explicitly contrast with suitecrm_list_leads or the other record tools, so an agent still has to infer that this tool is guidance-only rather than a record operation.

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