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

Beyond the annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false), the description discloses concrete side effects: the cert is re-issued and the web server is reloaded, plus the prerequisite advanced SSL mode. It does not explain failure/rollback behavior, so it is strong but not exhaustive.

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-loads the WRITE marker and core action, then conditions and endpoints. Dense but every clause carries information; the raw REST endpoint listing is slightly redundant for an agent but harmless.

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 4-parameter mutation with no output schema, the description covers action, side effects, prerequisites, parameter routing, and the underlying endpoints. An agent has everything required to invoke it correctly.

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 adds meaningful routing semantics by stating which parameter set applies to basic vs advanced SSL and why domain_id is conditionally needed. That is genuine value beyond the schema descriptions.

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: 'redeploy (renew) the Let's Encrypt certificate of a web application'. It clarifies the distinction from the sibling install tool by emphasizing re-issue/reload, so an agent knows this is not the initial issuance.

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?

Explicitly branches usage: basic SSL passes ssl_id from runcloud_get_webapp_ssl, advanced per-domain SSL additionally requires domain_id and advanced SSL mode (verified via runcloud_get_ssl_method). It names the exact sibling tools that supply each input, leaving nothing to inference.

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