Manage paid TLS certificate

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

Annotations already declare destructive=true, idempotent=true, openWorld=true, and readOnly=false. The description adds substantial context beyond annotations: required permission (certificates:manage), explicit user approval needed, private key never sent, idempotency key reuse rules, and refresh_certificate as a fallback for ambiguous outcomes. No contradiction with annotations.

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 core purpose, then layers preconditions, approval, reissue constraint, retry guidance, and auth requirement in a tight sequence. Every sentence adds necessary information without redundancy; no fluff.

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 covers purpose, preconditions, approval, key handling, and retry behavior well for correct invocation. It does not explain what the tool returns (e.g., a queued action identifier) or how to track status generally, which is a minor gap for a complex mutation tool.

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 description coverage is 75%, with descriptions for csr, idempotencyKey, certificate_order_id, and acknowledge_certificate_action. The description enriches the request union by enumerating allowed actions and adds idempotency key reuse semantics that go beyond the schema's field descriptions. It does not add detail on validation_method values, keeping it from a 5.

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 ('Queue') and resource ('paid-certificate management action') and enumerates the four action types (cancel, recheck/resend validation, change validation, reissue). The qualifier 'paid-certificate' distinguishes it from free-certificate tools. An agent can tell what this tool does 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?

Provides preconditions ('Read the product capabilities, current order, validation, and actions first'), an approval requirement ('Call only after explicit approval'), and a retry fallback ('reuse the same key only for the exact retry or call refresh_certificate'). However, it never addresses when to use this combined tool instead of the dedicated sibling tools (cancel_certificate, recheck_certificate_validation, resend_certificate_validation, change_certificate_validation, reissue_certificate) that perform the same individual actions, leaving ambiguous routing.

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