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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate destruction. It adds valuable context beyond annotations: the dry_run option (non-destructive way to preview) and the dependency on restart/redeploy for the change to take effect. There is no contradiction with the annotations.

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 three tight sentences with no filler. The core action is front-loaded, and the most important modifiers (is_preview, dry_run, restart requirement) are given in a logical order. Every sentence 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?

Given 5 parameters, full schema coverage, and a destructive operation with annotations covering safety, the description covers the essential operational details: deletion by key, preview selection, dry-run, and post-action restart. It does not explain error handling (e.g., key not found) but that's not strictly required for a delete operation. Minor gap, so a 4.

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 description coverage is 100%, so the schema already documents all 5 parameters. The tool description adds meaningful usage context for dry_run ('Use dry_run to check first') and clarifies the is_preview parameter specifically for applications. This goes slightly beyond the schema's basic descriptions, earning a 4.

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 a specific verb ('Delete') and a clear resource ('environment variable') with scope ('from an application or service, by key'). It also mentions the is_preview distinction for applications, which distinguishes it from sibling tools like set_envs and list_envs. The purpose is immediately unambiguous.

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 provides actionable guidance: use dry_run to check first and notes that changes take effect after a restart/redeploy. It also clarifies that is_preview applies only to applications. While it doesn't explicitly name sibling tools or state when not to use it, the context is clear enough for an agent to decide. Lacks an explicit alternative comparison, hence a 4 rather than a 5.

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

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

The description discloses key behavioral details beyond the annotations: the operation is queued, it rebuilds and restarts, it returns deployment uuids, and it requires the token's deploy permission. It also explains force behavior. No contradiction with the annotations exists; readOnlyHint=false aligns with the mutating nature of the operation.

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 compact and every sentence earns its place: operation, targeting options, force behavior, return value/follow-up, and permission requirement. Important constraints are front-loaded and nothing extraneous is included.

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 mutation tool with no output schema, the description covers the action, parameter selection, mutual exclusivity, return value, follow-up monitoring tool, and permission requirement. The agent has everything needed to select and invoke it correctly, including an appropriate next step via get_deployment.

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 description coverage is 100%, so the schema carries the parameter documentation. The description adds useful context for tag ('every resource with that Coolify tag') and clarifies the either/or relationship, but much of the resource/force semantics is already present in the schema. This meets the baseline without needing additional compensation.

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 a specific verb and resource: 'Queue a (re)deployment — rebuilds and restarts.' It clearly identifies the operation on applications/services via resource or tag, and the action is distinct from sibling lifecycle tools like restart_service, start_application, and stop_application.

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 clear guidance on targeting modes: 'Target either resource ... or tag,' and explains the force flag alternative for cacheless rebuilds. It also directs the agent to get_deployment for follow-up. It does not explicitly state when to prefer a sibling tool like restart_service, so exclusions are absent but the context is otherwise clear.

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

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

Beyond the readOnlyHint annotation, the description discloses two valuable behaviors: it returns candidates when the identifier is ambiguous, and it never returns secrets (webhook secrets, basic-auth passwords, compose files). This gives the agent important expectations about outputs and error handling that annotations alone do not provide.

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 two sentences and economically packed. The core purpose is front-loaded, followed by input flexibility and the critical secrets exclusion. No filler or repetition of annotation data is present, earning a top score.

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?

With no output schema, the description compensates by listing the returned detail categories and explicitly noting what will never be returned. It also covers identifier resolution and ambiguous-case errors, which are the main non-obvious behaviors. For a single-resource get, nothing essential is missing.

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 input schema already fully describes the parameter with 100% coverage ('Application uuid, exact name, or a unique part of its name or domain'). The description repeats the same semantics and adds the ambiguity-related error behavior, but that is behavioral transparency, not parameter meaning. Baseline 3 applies because the schema carries the full semantic load.

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 begins with a specific verb and resource: 'Get one application's details', then enumerates the exact fields returned (domains, status, git, build/start commands, ports, health check, limits, project/environment). This clearly distinguishes it from sibling list tools like list_applications and get_application_logs, leaving no ambiguity about its scope.

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 intended use case is clear: when you need a single application's full configuration. It also explains the accepted input formats and the ambiguity error behavior. However, it does not explicitly contrast with alternative tools like list_applications or get_deployment, though the 'one application' framing implies when to use it.

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

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

Annotations already communicate read-only safety. The description adds useful behavioral context by stating the tool returns only trailing lines and fails clearly when the app is not running, which is beyond what annotations alone convey.

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?

Two compact sentences front-load the core behavior and add a relevant failure note with no wasted words. The description is appropriately sized for the tool's simplicity.

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?

The description sufficiently conveys invocation conditions, failure behavior, and output scope for a simple read-only log tool. There is no output schema, so the exact response format is slightly under-specified, but this does not materially impair correct selection or calling.

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 description coverage is 100% and each parameter is already well-described in the schema. The tool description only restates the lines default and application context, adding little semantic value beyond 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 a specific verb and resource: retrieving the last lines of a running application's container logs, including the default line count. This clearly distinguishes it from the sibling management/list tools, none of which are log-focused.

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?

Establishes the applicable context (running application) and explicitly describes the failure mode if the app is not running. It does not name alternatives, but no sibling tool targets application logs, so this is sufficient practical guidance.

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

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

Annotations already declare readOnlyHint, and the description adds the permission requirement for log output (read:sensitive) and the line-limit behavior (default 100). This goes beyond the annotation by specifying a practical constraint, though it doesn't describe the response structure.

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?

Two concise sentences front-load the primary purpose (status + log lines) and immediately follow with the permission note. No filler or redundancy; every word adds value.

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 simple read-only tool with fully described parameters, this covers the essential context: what it returns and a critical permission caveat. The lack of return-format details is acceptable since no output schema is expected, and the annotations cover the safety profile.

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 100% so both parameters are fully described in the schema. The description adds only the nuance that lines come from the build/deploy log, which is a minor clarification that doesn't materially exceed what the schema already conveys.

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?

Clearly states it retrieves the status of a single deployment plus log lines, which distinguishes it from list_deployments (listing multiple) and get_application_logs (application logs). The verb 'get' plus resource 'deployment' is specific and unambiguous.

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 for a specific deployment via its UUID but does not explicitly contrast with siblings like list_deployments or get_application_logs. No 'when not to use' guidance is provided, leaving the agent to infer context.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description doesn't contradict them. It adds value by mentioning that it reveals whether the server is read-only and whether secrets are allowed to be revealed, which is not evident from annotations alone. However, it doesn't detail what specific endpoints are hit or potential side effects (though read-only), so a slight gap remains.

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 sentence that front-loads the primary purpose ('Check connectivity') and then lists the key return values concisely. It also includes the usage guidance in the same sentence, making it extremely efficient with no wasted words.

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 that the tool has no parameters, no output schema, and simple annotations, the description is fully complete for an agent to understand what the tool does and when to call it. The agent knows it returns version/health/base URL and read-only status, and the usage context is clear.

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?

There are no parameters, so the description need not explain any. The schema is empty with 100% coverage (effectively), and the description accurately states there are no inputs needed. This baseline of 4 for no-parameter tools is justified because the description doesn't introduce any confusion and is consistent with 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?

The description clearly states the tool's purpose: checking connectivity and returning version, health, base URL, and read-only/secret-reveal status. It is distinct from sibling tools, which are all focused on specific resources or actions, while this one is a meta/connectivity check.

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?

Explicitly instructs to call this tool first when other tools fail, providing a clear 'when to use' directive. It also conveys that it is a preliminary diagnostic tool, effectively differentiating it from the resource-specific siblings.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description only needs to add extra behavioral context. It does so by specifying filter semantics (case-insensitive substring on name/fqdn) and enumerating returned fields with status examples, which is especially valuable because no output schema exists.

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?

Two concise sentences: the first front-loads the purpose and output fields, the second gives the only invocation nuance. No filler and every sentence 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 simple read-only list tool with one optional parameter, no output schema, and read-only annotations, the description provides enough information to select and invoke correctly: output fields, filter behavior, and resource type. Missing pagination/ordering details are minor given openWorldHint and the simple scope.

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 sole parameter is fully documented in the input schema ('Case-insensitive substring matched against name and fqdn'), and the description largely restates that instruction. With 100% schema coverage, the description adds no new parameter semantics beyond what the schema already provides, so the baseline 3 is appropriate.

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?

Description clearly identifies a list operation on applications and enumerates the meaningful output fields (name, uuid, fqdn, status, git repo/branch, build pack, project, environment). This makes it easy to distinguish from sibling list_* tools and get_application.

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?

No explicit guidance on when to use this tool versus get_application or other list_* siblings. The only usage note targets the filter parameter ('Use filter to narrow...'), not tool selection, so an agent must infer the appropriate context from the tool name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe read operation. The description adds a valuable behavioral guarantee that 'Connection URLs and passwords are never returned', which is not derivable from annotations and directly affects agent expectations about sensitive data. This enriches the transparency beyond the annotation baseline.

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, efficient sentence that front-loads the action and resource, then lists the returned fields, and ends with a security note. Every word adds value; there is no filler or repetition. It is concise and well-structured for quick parsing by an agent.

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 simple list tool with no parameters and no output schema, the description covers the essential information: what is listed and what fields are returned, plus a security caveat. It does not mention pagination, sorting, or filtering, but these are unlikely to be needed given the tool's simplicity and the absence of input parameters. The description is sufficient for correct invocation.

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 tool has zero parameters, and the schema coverage is 100% (vacuously). With no parameters to document, the baseline for parameter semantics is 4, and the description does not need to add parameter-specific details. The description focuses on output fields, which is appropriate given the absence of inputs.

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 'List' and the resource 'standalone databases', specifying the exact fields returned (name, uuid, type, status, public exposure, project/environment). This distinguishes it from sibling list tools like list_projects or list_servers by making the database scope explicit, and the qualifier 'standalone' further narrows the resource 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 does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. However, the purpose is clear enough that an agent would infer usage for listing databases, and the sibling tools are named by resource, making the selection intuitive. No explicit exclusions or alternative routing are provided.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds value by revealing the ordering (newest first), the fields returned (status/commit/timestamps), and the special behavior for the unfiltered case (queued or in-progress). It does not contradict the annotations.

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 two sentences, front-loading the key distinction between the two modes. Every word earns its place, and the structure makes the behavior immediately understandable.

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 readOnlyHint and openWorldHint annotations, the description is quite complete. It explains the return fields, ordering, and the difference in scope. It doesn't describe pagination beyond the limit parameter, but the limit is already documented in the schema. No critical information is missing for a listing tool.

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 description coverage is 100% and both parameters have clear descriptions. The tool description adds conditional semantics (the application parameter changes the scope entirely), which goes beyond the schema's standalone definitions. It reinforces the meaning without redundancy.

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 tool lists deployments, with a specific distinction based on the application parameter. It describes the output content (newest first, status/commit/timestamps) and differentiates between filtered and unfiltered behavior, making it distinct from sibling tools like get_deployment which fetches a single deployment.

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 explicitly explains when to use the tool with the application parameter (to get that app's recent deployments) and without it (to see queued or in-progress deployments). However, it does not name alternatives or state when not to use it, though the two-mode behavior itself serves as clear guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses that values are masked to keep secrets out of the conversation, explains the masking format, and reveals the server-side requirement (COOLIFY_ALLOW_REVEAL=1) for plaintext. This is valuable behavioral context that annotations do not provide.

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?

Three sentences with no filler: it front-loads what is listed, then the masking rule, then the reveal caveat. Every sentence earns its place and the most safety-critical guidance is placed at the end without being buried.

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?

There is no output schema, so the description compensates by explicitly listing the output fields and flag names. It also covers the important masking behavior and the security-critical reveal condition. The schema covers all parameters, so no essential calling information is missing.

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 100%, so the schema already documents all parameters. The description adds context about reveal behavior but does not add new meaning to the parameters themselves; it correctly relies on the schema for parameter semantics.

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 names a specific verb ('List') and a precise resource ('environment variables of an application or service'), and explicitly enumerates the returned fields (key, uuid, flags). This clearly distinguishes it from sibling tools like list_applications, set_envs, and delete_env.

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?

It provides clear usage context: this is a read-only listing operation, and it gives an explicit when-not instruction for reveal ('avoid it unless the user explicitly needs a value'). It does not explicitly name alternatives such as set_envs or delete_env, but the read-only framing makes the distinction clear.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that projects are returned with their environment names, but it does not disclose pagination, sorting, or response shape beyond that.

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, front-loaded sentence with no filler. The verb, resource, and output detail are all present and every element 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 zero-parameter, read-only list operation with open-world semantics, this description is sufficient. It states what is returned and the annotations cover safety, so an agent can select and invoke the tool correctly without missing critical context.

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 tool takes zero parameters and the schema documents this completely with 100% coverage. With no parameters to explain, the description does not need to add parameter semantics; the environment mention is a useful extra but not required.

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 uses the specific verb 'List', names the resource 'Coolify projects', and specifies that output includes environments such as production/staging. This clearly distinguishes it from sibling listing tools by resource 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?

There is no explicit guidance about when to prefer this over list_applications, list_servers, or list_envs, nor any 'when not to use' note. The resource name implies its purpose, but the description leaves the comparison to inference.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, and the description is consistent with both. The description adds value by disclosing the output attributes (IP, reachability, proxy type), which helps the agent interpret results, though it leaves minor ambiguity about whether unreachable servers are included in the list.

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?

A single sentence with the verb and resource front-loaded, followed by scope and output fields. No filler; every phrase contributes to the agent's understanding.

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 zero-parameter list tool, the description names the resource, scope, and principal output fields, which is sufficient given the readOnly and openWorld annotations. With no output schema, the description carries the return expectations and does so, though pagination behavior and reachability semantics remain unstated.

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 tool has zero parameters, so the schema carries nothing to elaborate. Per the zero-parameter baseline, the description needs no parameter detail; it instead clarifies what the returned records contain, which is the meaningful semantic content here.

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 uses a specific verb ('List') with a clear resource ('servers attached to Coolify') and enumerates the returned attributes (IP, reachability, proxy type). This differentiates it from sibling list tools like list_projects, list_applications, and list_databases, which target different resources.

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 usage is implied — call this to inspect the Coolify server inventory — but the description never explicitly states when to use it versus alternatives or provides exclusion conditions. No sibling lists servers, so differentiation is carried by the resource name alone rather than explicit routing.

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

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

The annotations already convey readOnlyHint and openWorldHint, so the description does not need to restate safety. It adds the returned fields but no further behavioral details such as pagination, sorting, limits, or error behavior, which is acceptable for a simple read-only list.

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 concise sentence with the core action front-loaded. Every word contributes to defining scope and output without unnecessary filler.

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?

This is a low-complexity tool with one optional parameter and no output schema. The description names the returned fields, and the annotations cover safety and world-interaction context, so it is sufficient for correct invocation.

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 only parameter, filter, is fully described in the input schema with 100% coverage. The description adds no additional semantic meaning beyond the schema, so the baseline score of 3 is appropriate.

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 uses a specific verb and resource, 'List one-click / docker-compose services', and enumerates the returned fields. This clearly distinguishes it from sibling list tools such as list_applications and list_databases.

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 resource scope is implied by the description, but it does not explicitly say when to use this tool versus alternatives like list_applications or list_databases. There are no exclusions, fallbacks, or conditions stated.

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

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

Annotations indicate this is not read-only and not destructive. The description adds valuable context: it restarts containers without rebuilding, which implies a potentially brief downtime (not stated, but the nature of restart is clear). It also discloses it returns a deployment uuid to follow, which is a behavioral trait not in annotations or schema. No contradiction. The description carries the burden well given annotations exist.

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?

Two sentences with no fluff. The first sentence states the core action and its limits, the second states the return value and how to use it. Every word earns its place, and the critical information is front-loaded.

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?

This is a simple tool with one parameter and no output schema. The description tells the agent exactly what to expect (a deployment uuid) and how to proceed (follow with get_deployment). It explains the difference from deploy, which is the main contextual gap. It does not mention potential failure modes or prerequisites (e.g., application must exist), but those are likely inferred from the parameter description. Overall, adequate for the tool's complexity.

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 description coverage is 100% and fully explains the 'application' parameter (uuid, exact name, or unique part). The tool description does not add any additional meaning to the parameter beyond what the schema provides. Baseline of 3 is appropriate because the schema already handles semantics completely.

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 a specific verb ('Restart') and resource ('an application's containers'), and clarifies the scope ('without rebuilding'). It distinguishes itself from siblings like deploy, start_application, and stop_application by noting the change mechanism (runtime env vars vs build-time changes). An agent can immediately understand what this tool does and how it differs from related tools.

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 explicitly tells when to use this tool ('picks up runtime env var changes') and when not to ('build-time changes need deploy'), providing a clear decision rule against the most likely alternative. It also guides the follow-up action (use get_deployment with the returned uuid). It does not explicitly mention other siblings like restart_service, but the core distinction is covered. Would be a 5 if it named restart_service as an alternative for service-level restarts.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, and openWorldHint=true. The description adds that it restarts all containers and can pull images if `latest` is set, which are useful behavioral details. However, it doesn't mention potential downtime or side effects on connections, which could be relevant but isn't a contradiction.

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 two concise sentences, front-loaded with the core purpose and a concrete example. It avoids unnecessary detail and is easy to scan.

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?

The tool is a simple restart operation with full schema coverage and no output schema. The description provides the key usage context and the flag explanation. It could explicitly distinguish from restart_application, but the tool name and description make it reasonably clear.

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?

Both parameters are fully documented in the schema (100% coverage), including the meaning of `latest` and the flexible format for `service`. The description essentially repeats the schema's explanation for `latest` and adds nothing new about parameters, so it adds minimal value beyond 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?

The description clearly states the action ('Restart') and the resource ('a service (all its containers)'), and provides a concrete use case ('after changing its env vars'). This distinguishes it from sibling tools like restart_application, which targets applications rather than 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?

It gives a specific context for when to use the tool (after changing env vars) and explains the `latest` flag. However, it doesn't explicitly mention alternatives or when not to use it, such as comparing to restart_application. Still, the use case provides clear guidance.

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

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

Beyond the annotations (idempotent, non-destructive), the description discloses key behavioral traits: existing keys are updated, missing created, identical left alone (idempotency), values are never echoed, omitted flags keep current values, preview vs main separation, dry_run mode, and the requirement to restart or deploy for changes to take effect. This is rich behavioral context that significantly aids correct invocation.

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 dense sentence that front-loads the main purpose, then logically flows through key behaviors. Every clause adds necessary information without redundancy. It is appropriately concise for the complexity of the tool.

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 multiple parameters, flags, and side effects, the description covers all critical aspects: return format, value handling, flag semantics, preview vs main, dry_run, and the required follow-up actions (restart or deploy). No essential operational detail is missing, making it complete for correct 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?

Schema coverage is 100%, so each parameter already has a description. The tool description adds semantic meaning beyond the schema by explaining that omitted flags retain their current values, that is_preview targets the preview copy, and that dry_run is allowed even in read-only mode. It clarifies the upsert behavior and effect of flags, which goes beyond the basic parameter definitions.

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 a specific verb ('Upsert') and resource ('environment variables on an application or service'), and clearly distinguishes it from siblings like list_envs and delete_env by defining its scope and behavior. It also specifies the return status per key, which removes ambiguity about what the tool does.

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 provides clear context on when to use the tool, including that it performs an upsert and that changes take effect only after a restart or deploy. It also explicitly suggests using dry_run to preview, which is a usage directive. However, it does not explicitly name alternative tools or state 'when not to use', though the context makes it evident.

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

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

Annotations already indicate readOnlyHint=false, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds no further behavioral context such as side effects, permissions, or asynchronous behavior. It only explains parameter effects, which are already in the schema, so the added behavioral value is minimal.

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 two short sentences, with the main action front-loaded and flag semantics in the second sentence. Every word earns its place; there is no redundant or filler content.

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 start operation with two booleans and no output schema, the description covers the core action and flags. However, it omits information about return values, whether the operation is synchronous, or any prerequisites besides the application being stopped. Given the sibling set, some guidance on response format would improve completeness.

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 description coverage is 100%, and each parameter already has a description. The tool description repeats these (e.g., 'force rebuilds without cache' matches the schema). It adds no new meaning beyond the schema, so the baseline of 3 is appropriate.

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 action: 'Start (deploy) a stopped application.' It specifies the resource (application) and the state (stopped), which helps distinguish it from restart or deploy. However, it does not explicitly name sibling tools to differentiate, so it falls short of a 5.

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: start a stopped application. It does not provide explicit guidance on when to prefer this over deploy or restart_application, nor does it list exclusions. The flag explanations give context but no alternatives, making the guidance implicit rather than explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable context: the site goes down, and docker_cleanup prunes networks/volumes afterwards. It doesn't detail reversibility or permission requirements, but the core behavioral impact is disclosed.

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?

Two sentences, front-loaded with the most important consequence (site goes down), and the docker_cleanup note is concise. No wasted words.

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 destructive stop operation with annotations and full schema coverage, the description covers the key consequences and recovery path. It doesn't mention whether the operation is reversible or if there are prerequisites, but the essential information for an agent to decide and invoke is present.

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 description coverage is 100%, so the schema already documents both parameters. The description adds the behavioral consequence of docker_cleanup (prunes networks/volumes) and the application parameter's fuzzy matching is already in the schema. Baseline 3 is appropriate.

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 tool stops an application's containers and explicitly notes the site goes down until start_application or deploy. This distinguishes it from sibling tools like start_application, restart_application, and deploy.

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 when to use it (when you need to take an application down) and mentions the recovery path via start_application or deploy. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough.

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