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

Adds genuinely useful behavior beyond the annotations: it 'opens nothing by itself' and returns screens/buttons/fields instructions, which explains why readOnlyHint=true on an 'update' tool. The trailing paragraph about SuiteCRM's REST API v8 and OAuth2 client setup is administrative trivia that does not change how the tool is invoked and dilutes the behavioral signal. Nothing is said about what the returned instructions look like or how the relevant opportunity is located.

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 front-loads the key correction — it returns guidance and opens nothing — before the browser handoff. 'from ChatGPT, Claude or any AI agent' is filler, and the closing API/OAuth sentence is unrelated to selecting or calling this tool and could be cut entirely.

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 burden of explaining the contract, and it does communicate the guide-then-browse workflow. What is missing is how the specific opportunity is scoped and what the returned instructions contain, which matters for a tool whose entire output is prose instructions.

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 input schema is empty with 100% coverage, which would normally justify a 4. The gap is semantic rather than structural: an 'update opportunity' tool with no opportunity identifier, record reference, or field values leaves the agent guessing how the target is determined, and the description does not close that gap.

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?

Names a specific verb and resource (update opportunity) and then clarifies the actual behavior: it returns step-by-step SuiteCRM instructions rather than performing the mutation. That distinction from the cotlet_browser_* execution tools is stated explicitly. It stops short of distinguishing itself from the many other suitecrm_* record tools, which appear to follow the same guide pattern.

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 does route the agent onward ('then do it with the cotlet_browser_* tools in the user's SuiteCRM Cloud Browser'), giving an implied two-step workflow. However, it never says when to prefer this guide over, say, directly driving the browser, and with zero parameters it does not explain how the target opportunity is identified before calling.

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