dokploy_domain

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

With zero annotations, the description carries the full burden and it does disclose one meaningful trait: toggleEnable 'flips the enable flag blind', warning the agent that the end state is unknowable without a subsequent read. But it says nothing about the destructive side effects of delete, side effects of create (certificate generation, traefik config changes), authentication or permission needs, or idempotency. The single disclosed behavior is good, but coverage of the safety profile is thin.

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 extremely dense with zero fluff; every phrase earns its place and the 'action: params' pair format is compact and scannable. It loses a point only for the single run-on paragraph structure — bullets or line separators would materially improve parsability for an agent picking out one action's requirements.

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?

Complexity is high — 9 actions, 16 parameters, no annotations, no output schema — and the description covers the action/parameter dispatch matrix well. But material gaps remain: return values are unspecified, the meaning of path/port/https/certificateType is unexplained, validate's behavior and error semantics are unknown, and preview domainType handling is absent. For a dispatcher of this size, 'manage domains' plus a param map is not fully self-sufficient.

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 only 19%, so the description must compensate — and it does, but only partially. It adds the critical action→parameter association matrix, including the conditional nuances '( +serviceName for compose)' and '(include composeId+serviceName for compose domains)', which the schema cannot express. However, parameters like path, port, https, serverIp, and certificateType remain unexplained in either source, and host is never defined as a domain name vs. IP.

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 opens with 'Manage domains' — a specific verb and resource — and then enumerates nine distinct sub-operations (create, list, get, update, delete, toggleEnable, generate, canGenerateTraefikMe, validate), giving a precise map of the tool's surface. It is clearly the domain manager among the dokploy_* siblings, though it never explicitly names a sibling it is not, so it stops short of a 5.

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?

Each action is paired with the parameters it requires ('create: host+applicationId|composeId', 'get: domainId', etc.), giving an agent explicit invocation routing. The toggleEnable entry adds a strong preference rule — 'prefer update with enabled:true|false when you need a known end state' — which is genuine guidance. However, it never addresses when to use a sibling tool instead (e.g., dokploy_redirects, dokploy_dns_provider, dokploy_server), so cross-tool routing is left implicit.

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