dokploy_application

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

With no annotations, the description carries the full burden and does so well: it discloses that get masks env values, that saveEnvironment is a full replace, that setEnvVars is a server-side read-modify-write returning only changed key names, and that getEnvValuesUnsafe exposes plaintext values into the transcript and retained logs. It also surfaces the first-deploy failure/retry quirk and the narrow search index.

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 'action: params' pattern is consistent and front-loaded after a one-line purpose statement, and given 24 actions and 45 parameters nearly every clause carries information. It is still a single dense paragraph with no visual breaks, which makes scanning for a specific action slower than it needs to be.

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 of this complexity with no output schema and sub-50% schema coverage, the description gives an agent enough to invoke each action correctly, including which actions read versus mutate env state and what each returns in summary form. Only peripheral build/resource-limit parameters are left unaddressed, which is acceptable given they belong to the already-enumerated update path.

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% across 45 parameters, so the description must compensate, and it does for the action-critical ones — mapping action to required fields and clarifying semantics like 'KEY=VALUE pairs, full replace' versus upsert plus unset. However, a sizeable set of update parameters (command, cpuLimit, memoryLimit, replicas, buildArgs, dockerfile, publishDirectory, autoDeploy, createEnvFile) is named in a bare list without explanation or the schema documenting them.

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 the resource ('applications') and then enumerates every action with its required parameters, so an agent knows exactly which operation each action value performs. It also names related sibling tools (dokploy_project, dokploy_overview, dokploy_network) in contrasting contexts, distinguishing this tool from adjacent ones.

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?

Several actions carry explicit when-to-use guidance: getEnvValuesUnsafe is flagged 'use only when you need actual values', search is scoped to finding a known service rather than inventorying, and the deploy note warns of a retry pattern. It doesn't systematically contrast application actions against dokploy_compose or dokploy_database alternatives, so it stops short of full routing guidance.

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