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

The annotations declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description corroborates rather than contradicts them by stating it 'opens nothing by itself' and only returns instructions. That is exactly the kind of clarification that makes a 'create'-named read-only tool safe to invoke. It stops short of 5 because it says nothing about what the returned instructions look like structurally, whether any account/tenant context is required, or any limits on the response.

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 core behavior is front-loaded in the first sentence, which is good, but the framing 'from ChatGPT, Claude or any AI agent' is marketing filler and the trailing fragment 'Acumatica's official API: Yes.' is ambiguous rather than informative. Two of the three sentences earn their place; the rest is noise that slightly muddies an otherwise clear definition.

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?

For a zero-parameter, no-output-schema guidance tool, the description covers what an agent needs: no side effects, return content (screens, buttons, fields), and the required follow-up via cotlet_browser_* tools. The only real gap is that the meaning of 'Acumatica's official API: Yes' is never resolved, leaving a dangling claim.

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 there is no parameter meaning to add and the baseline of 4 applies. The description correctly does not waste space re-describing inputs and instead explains what the caller gets back.

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 makes clear that despite the name 'create', the tool does not write anything: it 'Returns how to do it in Acumatica step by step (screens, buttons, fields) and opens nothing by itself.' That is a specific verb-and-output statement that distinguishes it from mutation siblings like acumatica_create_ap_bill or acumatica_release_invoice. It loses a point only because the name/title ('Create AR invoice') points the opposite direction and the description never explicitly contrasts itself with those siblings.

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 states the downstream workflow clearly: 'then do it with the cotlet_browser_* tools in the user's Acumatica Cloud Browser,' which tells the agent this is a planning/guidance step, not the execution step. What is missing is any when-not guidance (e.g., when to skip the guide and use acumatica_list_open_invoices or an actual API write path).

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