dokploy_compose

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

The description goes well beyond a simple summary: it warns that get returns 'masked env summary — never values', flags getEnvValuesUnsafe as 'UNSAFE escape hatch' with output going to the transcript, and notes merge/full-replace semantics. For a tool with no annotations, this is exemplary disclosure of side effects and risks.

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 and action-oriented, with each action listed compactly. It is longer than typical, but the length is justified by the 21 distinct actions. The format is a bit run-on but remains scannable; the opening sentence provides a clear anchor.

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?

Given the tool's complexity (37 parameters, no output schema), the description covers many critical behaviors: masking, unsafe value retrieval, deployment failure caveat, and action-specific parameter requirements. It omits return details for most actions, but the coverage of safety and operation semantics is strong enough to prevent common misuse.

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 description maps parameters to each action (e.g., create: name+environmentId, move: composeId+targetEnvironmentId), adding context beyond the raw schema. It also clarifies behavior like 'saveEnvironment: composeId+env (full replace)' and 'setEnvVars: composeId + set?/unset? (merge inside the server)'. However, with 37 params and 62% schema coverage, some params remain underspecified without description-level detail.

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 Docker Compose services' and then enumerates every action (create, get, update, delete, deploy, etc.), making the tool's scope and operations explicit. It clearly distinguishes from sibling tools by focusing specifically on Docker Compose services.

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 concrete usage notes for several actions, e.g., 'loadServices: composeId (must deploy first)' and 'first deploy on new services may fail — retry immediately'. It does not explicitly name alternatives or when-not-to-use, but the action-specific prerequisites and caveats offer solid practical guidance.

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