dokploy_application

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

With no annotations provided, the description carries the full burden and does it well: it reveals that get returns a masked env summary and never values, saveEnvironment is a full replace, setEnvVars is a server-side read-modify-write with masked confirmation, and getEnvValuesUnsafe writes real values into the transcript/logs. It also exposes the first-deploy failure mode and the search-index limitation, which an agent cannot infer from the schema.

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 dense but appropriately sized for a 23-action tool, front-loaded with the resource name and using a consistent action: parameter pattern. Trivial grouped actions like start/stop/delete/markRunning/refreshToken/cleanQueues/killBuild/cancelDeployment are collapsed into one clause, and every sentence carries caveats or semantics rather than 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?

For a tool with no annotations and no output schema, this is remarkably complete: required IDs per action, env-var safety boundaries, log defaults, deploy retry behavior, and search limitations are all present. The remaining gaps are undefined return shapes for most actions and missing prerequisites for some update paths (e.g., sourceType github requiring repository+owner+branch), but the coverage is strong for the size.

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 only 49%, so the description compensates by mapping parameters to actions and adding semantics that are not in the schema: env KEY=VALUE full replace, set/unset upsert/remove behavior, traefikConfig omit-to-read, search fields, and log tail/since/search meaning. Still, the update action hand-waves some fields with 'etc.', and many numeric/resource fields remain unspecified in both schema and description.

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 identifies this as the application management dispatcher ('Manage applications') and enumerates every supported action: create, get, update, move, deploy, start/stop/delete, env operations, build type, traefik config, monitoring, logs, and search. It differentiates from sibling tools by noting the search index is narrower than dokploy_project/dokploy_overview and that it should be used to find a known service, not to inventory.

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 gives explicit usage guidance for search, naming dokploy_project/dokploy_overview as better for inventory, and warns that the first deploy on new services may fail and should be retried immediately. It also flags getEnvValuesUnsafe as an unsafe escape hatch. It does not systematically compare against every sibling (e.g., dokploy_compose, dokploy_deployment) for overlapping operations, but the key routing decisions are covered.

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