dokploy_network

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

With no annotations, the description carries the full burden and does well: it warns that recreate 'drops and re-adds the network so attached services are briefly disconnected', that resync 're-reads... without touching the network itself', and that inspect returns the raw Docker payload. It omits what remove destroys and whether operations are reversible or require elevated auth.

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?

Tight and front-loaded: it opens with the domain, then walks action-by-action with a consistent 'action: params' pattern. It is somewhat run-on and packs every branch into one paragraph, but nearly every clause earns its place.

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 12-param, 9-action tool with nested ipam and no output schema, the description covers the critical decision points and destructive side effects. It doesn't explain the return shape for list/get (which the agent may need) or the impact of remove, leaving modest gaps.

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 33% across 12 params, but the description compensates by mapping each parameter to its action (serverId for list/networksToSync, networkId for get/inspect/remove/recreate/resync, name+driver+internal+attachable+enableIPv4/IPv6+mtu+ipam for create). This adds real meaning beyond the bare enum/type schema, though constraints like driver/overlay semantics are left to the schema.

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?

States 'Docker network management' then enumerates the nine actions with a specific verb+object for each (list, inspect, recreate, resync, import, etc.). It also names the sibling tools (dokploy_application/dokploy_compose) used for the adjacent task of attaching networks, distinguishing it from general app/compose tools, though it doesn't explicitly contrast against dokploy_docker or dokploy_docker_volume.

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 per-action conditions, e.g. networksToSync is for networks existing on the host but untracked, and import consumes names from networksToSync. It routes the agent onward for attachment ('Attach networks to workloads with dokploy_application update networkIds'). However it doesn't state exclusions or prerequisites (e.g. when not to use recreate vs resync beyond a single clause).

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