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

Annotations only declare readOnly=false, destructive=false, idempotent=false, openWorld=true. The description adds the facts that matter most: real money is billed by the provider, confirm=false is a validating dry run that returns a cost estimate, a hard 10-server-per-call cap, permission failures for unreachable clusters, and that the call returns an asynchronous Cycle job. That is materially more than the annotations convey.

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?

Front-loaded with the cost warning, which is exactly what an agent must see first, and each sentence carries information. It is somewhat long, and the confirm approval rule is stated twice (description and confirm parameter), which is deliberate emphasis but mild redundancy.

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 6-parameter mutation tool with no output schema and no destructive annotation, the description covers the safety profile, the async return path (Cycle job tracked via check_server_provisioning), the discovery prerequisite, and the cost consequence. Nothing an agent needs to invoke it correctly is missing.

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?

Schema coverage is 100%, so the baseline is 3; the description still earns credit by explaining the confirm dry-run/approve semantics and the 10-server aggregate limit that the schema alone does not spell out. It does not, however, add much on cluster/provider resolution or the nested server fields.

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?

States a specific verb and resource ('Provision new servers (bare metal or VMs running CycleOS) from a connected infrastructure provider into a cluster'), and immediately distinguishes the tool's cost-bearing nature. An agent can tell this is infrastructure provisioning rather than an application/VM deploy without opening the schema.

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?

Explicit when-to-use guidance: dry run without confirm, real deployment only after explicit user approval of the exact plan and cost, plus named prerequisites (get_deployable_server_models) and follow-up (check_server_provisioning). It does not, however, differentiate itself from near-name siblings like deploy_virtual_machine or deploy_application, which an agent could plausibly confuse with this.

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