coolify_update_service_envs_bulk

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

The tool has no annotations, so the description must carry the full burden of behavioral disclosure. It discloses that the tool writes (creates/updates) data, which is critical for the agent's decision-making. However, it does not disclose potentially important behaviors like whether the operation replaces all envs or patches them, whether it triggers a redeploy, what happens with existing envs not in the array, or if there are idempotency or rate-limit considerations. The description provides basic transparency but lacks sufficient depth for a mutation tool.

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 a single, well-structured sentence that includes the WRITE tag, the action, the resource, and the behavioral nuance of creating or updating. Every part of the sentence adds value: it identifies the operation type, the resource, and the method of operation (upsert). There is no wasted text, and the information is front-loaded with the most critical detail. It is highly efficient.

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 has 2 parameters with 100% schema coverage, no output schema, and no annotations, the description covers the basic purpose and states that it creates or updates. However, it is incomplete for a bulk-write operation—it does not explain what the return value looks like, whether the operation is synchronous or asynchronous, or how the system handles the batch (e.g., all-or-nothing vs. partial success). The description is minimally viable but leaves gaps that could cause incorrect agent usage.

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 schema description coverage is 100%, meaning the schema itself documents both parameters (uuid and envs). The description adds value by explaining the operation in terms of the environment variables array—that it 'bulk update[s]... environment variables' and 'creates or updates' them. This provides semantic context about the purpose of the 'envs' parameter beyond the schema's bare 'Array of environment variables to set'. The description correctly sets expectations for the bulk operation.

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 states the verb 'Bulk update', the specific resource 'environment variables for a Coolify service', and lists an important behavioral detail 'creates or updates'. However, it does not distinguish itself from closely related sibling tools like 'coolify_update_service_envs_bulk' (itself) or 'coolify_update_database_envs_bulk', which have nearly identical functionality for different resource types. The leading '[WRITE]' tag is helpful for identifying the action type.

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 implies usage when the agent wants to set multiple environment variables at once on a service, with the note that it both creates and updates. However, it does not explicitly state when this tool should be used versus alternatives like 'coolify_create_service_env' (single env) or 'coolify_delete_service_env', nor does it mention any prerequisites (e.g., service must exist). The sibling tool list is extensive, but the description offers no comparative guidance.

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