caddy_tls

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

Annotations already indicate idempotent behavior and non-destructiveness. The description adds minimal behavioral context beyond the actions themselves, such as working on fresh/existing instances. It does not contradict annotations, and while it does not provide deeper details like side effects or permission requirements, the annotations reduce the burden. The added info is useful but limited.

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 appropriately concise at two sentences. It front-loads the primary purpose, then lists actions with brief clarifications. Every sentence adds value, with no filler or redundant wording.

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?

While there is no output schema, the tool's scope is limited and clearly described. The actions and their parameter mappings are covered by the description and schema, and the annotations cover safety concerns. The only minor gap is not describing the return format of 'status', but overall completeness is strong for the tool's simplicity.

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 input schema has 100% parameter description coverage, clearly defining each parameter and its association with an action. The description essentially restates the action enum but adds no deeper syntactic or formatting details beyond what the schema provides. Since schema coverage is complete, a baseline of 3 is appropriate.

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 clearly states the tool's function ('Get or configure TLS/HTTPS settings') and enumerates specific actions with their meanings. It distinguishes itself from sibling tools like caddy_config_get or caddy_status by focusing specifically on TLS/HTTPS settings and ACME configuration.

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?

The description provides some context by stating it works on both fresh and existing Caddy instances, but it does not explicitly state when to prefer this over related tools (e.g., caddy_config_get/set) or specify conditions under which it should not be used. No alternatives are mentioned, so guidance is implied rather than explicit.

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