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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with 'opens nothing by itself', which resolves the apparent mismatch between the name 'create_work_order' and a read-only hint. It adds real context beyond annotations: the output is human-readable screens/buttons/fields instructions, and the official API is blocked behind a support-issued token. Return-value format is stated but pagination/structure detail is minimal.

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 description is front-loaded with the key behavior, which is good, but the final sentence about RazorSync's official API is tangential and reads as justification rather than guidance. The clause 'from ChatGPT, Claude or any AI agent' is filler. Tightening to two sentences would 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 zero parameters and no output schema, the description carries the burden of explaining what comes back, and it does: step-by-step screens, buttons and fields. It also names the follow-up tool family. The only gap is that it does not state prerequisites for the browser session (e.g., the RazorSync Cloud Browser must already be open).

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 there is nothing for the description to disambiguate. The absence of arguments is consistent with a pure guidance tool, and the description does not falsely imply inputs.

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 outcome: it returns step-by-step instructions for creating a work order in the user's own RazorSync account rather than performing the action. This clarifies the potentially misleading verb in the name/title ('Create') and distinguishes it from the cotlet_browser_* action tools. It stops short of a one-line crisp definition because the core purpose is buried mid-sentence behind scope framing.

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 explicitly tells the agent the workflow: call this for guidance, then execute with cotlet_browser_* tools in the user's RazorSync Cloud Browser. It also implies a when-not via the API note (the official token-based API requires obtaining a token from RazorSync support, so it is not immediately usable). No explicit exclusions against other siblings like razorsync_list_customers, but the usage context is clear.

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