Manage free TLS certificate

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

Annotations already flag destructive=true and openWorld=true, but the description adds context the annotations cannot convey: managed-key renewal happens automatically, customer_csr renewal requires a fresh public CSR for the unchanged authorized names, the private key cannot be exported, and the call requires the certificates:manage permission. This is exactly the kind of prerequisite and side-effect disclosure a mutation tool needs, with no contradiction of the annotation set.

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?

Five sentences, each doing distinct work: purpose and action list first, then renewal semantics, then the approval gate, then the fallback read, then the private-key boundary and permission. Nothing is redundant and the most important constraint (user approval) is not buried.

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 output schema, the description sensibly tells the agent how to interpret an ambiguous response by falling back to get_free_certificate. It covers prerequisites, permissions, and side effects well for a destructive dispatcher; the one gap is that it never resolves the overlap with the four single-action sibling tools.

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 67%, so the schema documents the request id, the acknowledge flag, and the CSR field. The description still adds meaning by tying the CSR requirement to the customer_csr renewal path, noting the authorized names must be unchanged, and reinforcing that the private key must never be transmitted. It stops short of describing the request-action variants in prose, but the schema's const values carry that.

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 verb and resource ('Request one free-certificate lifecycle action') and enumerates the exact action set (early renew, revoke, recheck, cancel before issuance), which cleanly separates it from get_free_certificate. It does not, however, explain why an agent would use this dispatcher instead of the per-action siblings renew_free_certificate, revoke_free_certificate, recheck_free_certificate, and cancel_free_certificate, leaving a real selection ambiguity.

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 gives explicit sequencing ('after reading its current state'), a hard prerequisite ('Call only after explicit user approval'), and an alternative path ('read get_free_certificate before deciding whether another action is needed'). It also names the tool it is not (get_free_certificate) in the read/act split, so the when-to-use guidance is unusually complete.

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