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

With no annotations provided, the description must disclose behavior on its own. It indicates the operation is destructive by requiring --allow-destructive and confirm:true. It also scopes the action to 'in-progress' deployments. Yet it does not explain side effects, the 'fenced' term, or what happens to the deployment afterward, so transparency is adequate but not thorough.

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-loaded with the primary action and resource, and contains no filler. Every word adds value, making it highly concise and effective.

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?

Considering there is no output schema and no annotations, the description covers the essential purpose and prerequisites but omits details like the meaning of 'fenced', behavior when the deployment is not in progress, and the return value. It is minimally sufficient for a simple cancellation tool but leaves some gaps for the agent to infer.

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 parameters. The description adds only minor value by reinforcing that confirm:true is required for destructive operations and that the deployment is identified by UUID. This is a baseline 3 with a small amount of extra context.

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 cancels an in-progress deployment by UUID, using the verb 'cancel' and specifying the exact resource type. This distinguishes it from sibling tools like deploy (which starts deployments) and delete_resource (which removes entire 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 description gives clear context that the tool is for cancelling in-progress deployments and specifies the required confirm flag and --allow-destructive. However, it does not explicitly mention when not to use it or compare it to alternatives, keeping it at a 4.

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 warns that stop and restart are destructive and require confirm:true, and notes deployment_uuid returns for applications. However, it mentions an '--allow-destructive' flag not present in the schema and uses 'fenced' without definition, causing confusion. No annotations exist, so the burden is on the description.

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 succinct sentences with front-loaded purpose; no waste except for the unexplained 'fenced' and stray CLI flag. It's concise but not perfectly clean.

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 no output schema and no annotations, the description should cover return behavior and prerequisites more thoroughly. It explains start/restart return for apps but not for databases/services, and doesn't clarify the 'fenced' qualifier or the allow-destructive flag. It covers the main safety and return aspects but remains incomplete for a 7-param 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?

The description adds meaning to the action parameter by clarifying which actions are destructive and their confirmation requirement, and adds return-value semantics for applications. The schema already covers uuid, confirm, dry_run, instance, and instant_deploy; the description goes beyond these by explaining action-specific behavior, though the '--allow-destructive' reference is confusing.

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 'Start, stop, or restart a Coolify resource', naming the verb and resource type, and differentiates from sibling tools like delete_resource, deploy, and update_resource. The term 'fenced' is unclear but doesn't obscure the core purpose.

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 alternatives like deploy or delete_resource. It only notes destructive actions require confirm, not when to choose this lifecycle tool.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool is FENCED, requires --allow-destructive and confirm:true, and characterizes the write as code/credential write. This is significant safety-relevant behavior. It does not detail all side effects, but the critical guardrails are covered.

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 pack a large amount of high-value information: the core purpose, the discriminating logic, and the critical fencing requirement. The description is front-loaded and wastes no 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 22 parameters and no output schema, the description does not explain each parameter but relies on the rich schema. It does provide the essential high-level decision tree and safety context. It omits some conditional nuances (e.g., build_pack requirements), but the schema covers individual fields, making this sufficient for a create 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 coverage is 100%, so the baseline is 3. The description adds relational semantics beyond individual field docs: it explains that `kind` discriminates among three types, `source` is a sub-discriminator for applications, `engine` is for databases, and `service_type` XOR `docker_compose_raw` (base64) applies to services. This helps the agent correctly combine parameters.

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: 'Create a new Coolify resource.' It clearly distinguishes from sibling tools like update_resource and delete_resource by using 'create' and explaining the resource-kind discriminator. This makes the tool's purpose 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 clearly implies the tool is for creation and provides a decision tree via `kind` (application/database/service) with sub-discriminators. It does not explicitly state when not to use it or compare with alternatives, but the context is clear and no exclusions are needed beyond obvious creation tasks.

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 explicitly discloses the permanent, irreversible nature of the delete and the mandatory confirm parameter, which is critical for a destructive operation. It also mentions the --allow-destructive flag, indicating an extra safety gate. However, it does not elaborate on associated data loss or the exact scope of deletion, and it omits mention of dry_run's preview capability, leaving some behavioral aspects to the schema.

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, focused sentence that front-loads the action and highlights the critical confirm requirement. It contains no filler and every word adds value, making it appropriately concise.

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 tool with no annotations, the description adequately warns about permanence and the confirmation requirement, which are the most critical operational details. The schema covers parameter enumerations and dry_run behavior, so the description complements rather than duplicates it. However, the lack of any mention of return behavior or the meaning of `uuid` leaves minor gaps, but overall it is sufficient for safe 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 schema describes confirm, dry_run, and instance, but type and uuid lack descriptions, giving 60% coverage. The tool description reinforces confirm's necessity but adds no new meaning for type, uuid, or dry_run, and introduces an external flag not present in the schema. Thus, it does not significantly compensate for the undocumented parameters.

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 identifies the tool's function with the verb 'Delete' and specifies the target as 'a Coolify resource,' emphasizing permanence. The action is distinct from sibling tools like create_resource, update_resource, and control_resource, so the purpose is 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 a key usage requirement—confirm:true and the --allow-destructive flag—which is essential for executing a destructive operation. However, it does not explicitly differentiate when to use this tool versus alternatives like control_resource for temporary changes, nor does it mention dry_run as a safe preview option. The guidance is limited to prerequisites, not broader usage 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?

With no annotations provided, the description carries the burden of disclosure. It clearly states the FENCED requirement: 'requires --allow-destructive and confirm:true (code/credential write)', providing critical safety and permission context beyond the schema. This adds value without contradicting any 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-loaded with the primary action, and cleanly separates the safety note. Every word earns its place without unnecessary elaboration.

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 7 parameters, no output schema, and no annotations, the description covers the core action, selection methods, options, and a critical safety constraint. It does not explain dry_run or return values, but the schema covers parameters, and the absence of output schema does not require over-explanation.

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 baseline is 3. The description adds minor semantic grouping ('by UUID or tag', 'force-rebuild', 'pull-request preview') that maps to uuid/tag, force, and pr parameters, but it does not provide additional syntax or details beyond the already-rich 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 uses the specific verb 'Trigger a new deployment' and identifies the target resource as 'an application (by UUID or tag)'. It also mentions optional force-rebuild and pull-request preview, distinguishing it clearly from siblings like cancel_deployment or get_deployments.

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 context for when to use the tool: to trigger a deployment, optionally with force rebuild or PR preview. It does not explicitly mention alternatives or exclusions, but the purpose is unambiguous and distinct from deployment-related 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?

With no annotations provided, the description carries the full burden. It discloses blocking behavior, progress notifications, return content (per-resource statuses and logs tail on failure), and the FENCED requirement for --allow-destructive and confirm:true. This is substantial useful context, though it doesn't mention timeout behavior explicitly or what happens on internal errors.

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: three sentences, each providing valuable information. It front-loads the primary purpose, then adds behavioral details and safety constraints without redundancy or fluff.

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 8 parameters, no output schema, and no annotations, the description provides a good deal of context: blocking behavior, terminal states, progress notifications, return values, failure logs, and destructive-confirmation requirements. It would be slightly more complete if it explicitly addressed timeout return behavior, but the schema covers that, and the overall picture is well-rounded.

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%, so the input schema already documents all 8 parameters with descriptions. The description adds little parameter-specific meaning beyond what the schema already provides (e.g., confirm being mandatory and dry_run behavior are already in the schema). Thus, the description adds no significant extra parameter semantics, warranting the baseline score.

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+resource: 'Trigger a deployment and block until it reaches a terminal state'. It clearly distinguishes this tool from siblings by emphasizing blocking behavior and terminal-state outcomes, and it enumerates the terminal states (finished/failed/cancelled/skipped), leaving no 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 implies the use case: when you need to trigger a deployment and wait for its final outcome, with progress notifications and status/logs. However, it does not explicitly compare to sibling tools like 'deploy' or state when NOT to use this tool, and it lacks concrete alternative 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?

With no annotations, the description carries the burden. It discloses the two operational modes and pagination support. It doesn't explicitly state read-only status, but 'List' implies it. Slight ambiguity about pagination applying only to history mode is resolved by schema.

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 main action, no wasted words. Perfectly concise.

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 covers the core behaviors and parameter usage. It doesn't describe return format, but for a list tool without output schema, this is acceptable. The tool is adequately scoped for selection and 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?

Schema already documents all parameters (100% coverage). The description adds the semantic distinction that app_uuid toggles modes and skip/take are pagination controls, which is valuable 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?

Clear verb 'List' with specific resource 'deployments', and distinguishes two modes: active deployments (no args) or history for a specific app (app_uuid). This differentiates it from siblings like list_resources and get_logs.

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 clear context on when to use each mode and pagination parameters. However, it doesn't explicitly mention alternatives or when not to use this tool, so not 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?

With no annotations provided, the description carries the full burden. It discloses the API endpoint and the host-ops requirement, implying a read operation. However, it does not describe the return format, size limits, or potential side effects. The reference to 'Task 31' is an implementation detail that does not clarify behavior for an agent.

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 front-loaded with the purpose and uses bullet points for clarity. It is relatively concise, though the trailing 'wired in Task 31' is irrelevant and adds noise. Overall, the structure is 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?

The description lacks critical context for an agent to fully understand the tool's behavior without relying on external knowledge. It does not explain the return value structure, how 'instance' affects the request, or clarify the ambiguous '--enable-host-ops' requirement. Since there is no output schema and no annotations, this is insufficient.

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?

While the schema already describes all parameters (100% coverage), the description adds meaningful context: it ties the 'lines' parameter to the API query string, and clarifies that 'database' and 'service' kinds have additional prerequisites. This goes beyond the schema 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 clearly states the tool fetches a log snapshot for a Coolify resource, with a specific verb and resource type. It distinguishes from sibling tools like get_resource or get_deployments by focusing on logs, and further differentiates between application, database, and service kinds.

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 context on when to use the tool by explaining kind-specific behavior: applications use a REST API endpoint, while databases/services require --enable-host-ops. It does not explicitly mention exclusions or alternatives, but the prerequisites are useful for selection.

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 indicates a read-only 'Get' operation, but with no annotations provided, it carries the full burden of behavioral disclosure. It does not mention what happens when the UUID is invalid, whether authentication/instance selection is needed, or confirm that no modifications occur. The read-only implication is clear, but no additional behavioral context 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?

The description is a single, direct sentence that conveys purpose and scope without redundancy. It is appropriately sized for a simple getter 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 simple read operation with fully documented parameters and no output schema, the description is adequate: it names the resource types generically, but does not detail the response shape. Since 'full details' implies a comprehensive return, and format is not explained, there is a minor gap. However, the overall simplicity keeps completeness high.

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 fully describes all parameters (100% coverage), including the enum for type and descriptions for uuid and instance. The description adds little beyond restating 'by type and UUID'—it does not explain the instance parameter or the meaning of each resource type. With high schema coverage, the baseline of 3 applies and the description provides no extra value.

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 operation ('Get full details') and the target ('a specific Coolify resource'), with precise scoping ('by type and UUID'). It is distinct from sibling tools like list_resources (lists all resources) and get_logs/get_deployments (which target other aspects). The verb and resource are 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?

No guidance is provided about when to use this tool versus alternatives. It does not mention that list_resources should be used to discover UUIDs, or that get_logs/get_deployments serve different purposes. The description implies its own use but offers no explicit context or exclusions.

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?

With no annotations provided, the description carries the full burden. It implies read-only behavior via 'Query' and discloses the default summary/list behavior and 'include:true' modifier. However, it does not explicitly state that no data is modified, nor does it mention pagination, errors, or authentication requirements—adequate but with clear gaps.

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-loaded with the main purpose, and every word contributes to understanding the tool's scope and actions. There is no redundancy or 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?

The tool is moderately complex (4 parameters, 5 actions, no output schema). The description lists the action names but does not explain what each action returns or any other behavioral details. Since there is no output schema, the description should compensate by clarifying each action, but it only elaborates on 'list'. This leaves 'get', 'validate', 'resources', and 'domains' underspecified, though their names are reasonably self-explanatory.

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 is already described in the schema. The description's note 'list (summary fields by default; include:true for full)' adds no new information beyond the schema's own descriptions for 'action' and 'include'. It meets the baseline but provides no extra semantic value.

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 queries Coolify servers and enumerates specific actions (list, get, validate, resources, domains), distinguishing it from sibling tools like 'get_resource' and 'list_resources' which target resources generally. The verb 'Query' plus the resource and action list make the purpose 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?

'Query Coolify servers' provides clear context for when to use this tool, and the action list (e.g., list, get, validate) indicates common operations. However, it does not explicitly mention when not to use it or name alternatives, so it falls one step short of full 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?

No annotations are provided, so the description carries the full burden. 'Browse' implies a read-only listing operation, and 'resource catalog' indicates it returns data, but it does not disclose return format, pagination, error behavior, or any potential side effects. This is basic but incomplete behavioral transparency.

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, no filler, and front-loads the purpose. Every word earns its place, making it highly concise and well-structured.

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 simple with good schema coverage, and the description adds key workflow context. However, since there is no output schema, the description could have briefly mentioned the return format (e.g., a list of resources). Still, the current description is largely complete for a browsing 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% (both instance and resource have descriptions). The description adds a workflow hint ('server type and location') that maps to enum values, but it does not add meaning beyond what the schema already provides. 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's function ('Browse Hetzner Cloud resource catalog') and explicitly ties it to the provisioning workflow ('Use before provision_hetzner to pick a server type and location'). This distinguishes it from generic list tools and clarifies its specific 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?

'Use before provision_hetzner to pick a server type and location' provides clear, explicit when-to-use guidance within the provisioning workflow. However, it does not name alternatives or state when not to use it, so it falls slightly short of 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?

With no annotations, the description carries the burden and explicitly notes that it 'Never returns tokens or other secrets,' adding a behavioral guarantee beyond the schema. It also discloses the scope (server-global) and the content of the list, providing adequate transparency for a read-only list 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?

Three short sentences front-load the main purpose, then add a safety note and a routing tip. No waste.

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 discovery tool with no output schema, the description mentions all relevant return fields and the safety constraint. It is complete enough for an agent to know what the tool returns and how to use the result.

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 single optional 'instance' parameter is fully documented in the schema, and the description reinforces that it is not used for routing here. Since schema coverage is 100%, the description adds no new parameter syntax but usefully repeats the cross-tool routing advice.

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' and identifies the resource as 'Coolify instances this server is configured to drive,' with the fields returned ('names, base URLs, default, and per-instance host-ops/destructive flags'). This distinguishes it from sibling tools like list_resources or get_servers by focusing on instances and their routing configuration.

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 states that the instance list is server-global and directs users to pass an instance name to any other tool for routing, which gives clear usage context. It does not explicitly list when not to use this tool or name alternative list tools, but the routing instruction serves as 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?

With no annotations, the description carries the full burden. It discloses the broad scope and optional filter but omits behavioral details such as the read-only nature, the effect of the instance parameter, pagination, or permission requirements. Some context is added, but it is not rich.

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, front-loaded sentences with a parenthetical enumeration. Every word contributes, and there is no filler or repetition.

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, the description covers the main purpose and type filter, but fails to mention the instance parameter, which is important for multi-instance setups. Although the schema fills the gap, the description's ambiguity about instance scoping leaves room for misinterpretation.

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 already has 100% coverage for both parameters. The description only redundantly mentions the type filter and does not describe the instance parameter at all, so it adds little over 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 states a specific verb ('List'), a specific resource ('Coolify resources'), the scope ('across all projects'), and enumerates the resource types. It also notes the optional type filter, which distinguishes it from more specific tools like get_resource or list_instances.

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 use for listing resources but does not explicitly contrast with alternatives or specify when not to use it. No exclusions or alternative tool names are mentioned, so the usage guidance is only implied by the task description.

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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It mentions that the tool can create, update, and delete, implying mutability, but provides no details on side effects, permissions, reversibility, or confirmation requirements. The confirmation requirement for delete is only present in the input schema, not the description, so the agent is left without warning about destructive actions.

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 at two sentences, front-loading the core purpose. The second sentence is somewhat dense with a long list of fields, but each item adds relevant detail. It avoids unnecessary filler, so it remains appropriately sized for the tool's complexity.

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 (9 parameters, multiple actions, nested objects, no output schema), the description gives a high-level overview but misses some important distinctions. For example, it does not clarify the difference between 'list' (schedules) and 'executions', nor between 'delete' and 'delete_execution'. However, the input schema covers many required-field constraints, so the description does not need to repeat those. Still, the ambiguity around action applicability leaves 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?

The description adds meaning beyond the schema by explaining that `fields` holds backup schedule parameters and lists which ones are required or optional for create/update. It specifically notes that `frequency` is a cron expression and includes the wildcard `database_backup_retention_*`, which is not obvious from the schema alone. This compensates for the 78% schema coverage by clarifying usage of the `fields` object.

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 function: 'List, create, update, or delete database backup schedules and executions.' It names a specific resource (database backup schedules/executions) and distinct verbs for each action. The qualifier 'Only applicable to databases' further narrows scope, differentiating it from sibling tools like manage_scheduled_tasks.

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 by specifying that the tool is 'Only applicable to databases,' which serves as an exclusion criterion. It also gives actionable guidance for create/update by stating that schedule fields go in `fields` and that `frequency` is required. However, it does not explicitly name alternative tools or state when not to use this tool beyond the database scope.

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?

With no annotations, the description carries the full burden. It discloses key behavioral traits: list returns a redaction_hint, set upserts via bulk API, delete is destructive and requires confirmation, and dry_run is supported. However, it does not mention side effects beyond deletion, error conditions, or authentication/rate limits, which are common gaps but not required given the tool's purpose.

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 around 70 words, front-loaded with the main purpose, and uses action= prefixes to organize behavior. Every sentence adds concrete information without redundancy, achieving high information density in a compact form.

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 no output schema and 10 parameters, the description does well: it explains list's output, set's bulk capability, and delete's requirements. It falls short by not describing return values for set/delete or error behaviors, and it omits that type and uuid are required across all actions (but that is in the schema). Overall, it covers the core operational 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?

Although schema coverage is 100%, the description adds crucial relational meaning: it links action=set to key/value and vars, explains env_uuid comes from list, and ties confirm/dry_run to delete. This goes far beyond the schema's static descriptions and helps the agent choose the correct parameters per action.

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 starts with a clear verb+resource statement: 'Manage environment variables for a Coolify resource (application, database, or service).' It then enumerates the three actions (list, set, delete) with specific behavioral details, making it distinct from sibling tools like manage_storage or manage_backups.

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 for when to use each action (list for viewing, set for upserting, delete for removal) and specifies prerequisites like env_uuid from list. It also states that delete requires confirm:true. However, it does not explicitly compare with alternative tools or mention when not to use this tool, so it misses the explicit exclusion guidance that would earn 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?

With no annotations, the description carries the transparency burden. It discloses that create/update are credential writes, requires confirmation, and mentions the collection-level PATCH nuance for update (uuid in body). This adds valuable non-obvious behavioral context, though it doesn't explain what 'fenced' means or potential side effects of delete.

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 sentences, front-loaded with the purpose, then a concise action list, then critical operational details. No filler or redundant 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?

Given the tool complexity (9 params, 5 actions) and no output schema, the description covers essential warnings and nuances but could elaborate on return values or per-action behavior. However, the rich schema descriptions compensate, making the description adequate.

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 baseline is 3. The description adds extra meaning by linking confirm to credential writes and explaining that update uses a collection-level PATCH with uuid in the body. This goes beyond the schema field descriptions.

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 manages Coolify SSH private keys and enumerates the supported actions (list, get, create, update, delete). This is a specific verb+resource and distinguishes it from sibling tools like manage_server or manage_storage.

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 context on how to perform actions, notably that create/update are fenced credential writes requiring --allow-destructive and confirm:true. It doesn't explicitly name alternatives, but the tool's scope is clear relative to 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?

With no annotations, the description carries the full burden, but it only hints at destructive operations with '(fenced)' without explaining what that entails. It fails to disclose side effects, required permissions, or behavior of actions like delete. The schema covers the confirm flag, but the description adds little beyond a vague safety signal.

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 concise, front-loads the purpose, and uses a compact action list. It is not overly verbose, though the actions could be presented in a more structured way (e.g., categorizing by resource type).

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 (8 parameters, 9 actions) and lack of output schema, the description is incomplete. It does not explain what each action returns, mention prerequisites (e.g., needing a UUID for get), or provide context beyond the action names. The schema compensates for some parameter details but not overall workflow 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?

Schema description coverage is 100%, so the structured field descriptions already document all parameters. The description adds no additional parameter semantics beyond what the schema provides, maintaining the baseline.

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 identifies the resource (Coolify projects and their environments) and enumerates specific actions (list, get, create, update, delete). The verb 'Manage' is generic, but the action list provides specificity and distinguishes it from sibling tools like manage_env or manage_server.

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 no guidance on when to use this tool versus alternatives. It does not mention that environment-specific tools (e.g., manage_env) should be used for environment variables, nor any prerequisites or contexts for the various actions.

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?

With no annotations, the description carries the transparency burden. It meaningfully discloses that create/update are code-execution writes with special safety requirements, and the 'fenced' label hints at guarded behavior. However, it does not clarify whether delete also requires confirm (schema says yes) or explain what 'fenced' actually means, leaving some behavioral gaps.

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 crisp sentences. The first sentence front-loads the action list and resource; the second adds a targeted safety note. 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 the tool's complexity (13 parameters, 5 actions, no annotations or output schema), the description is adequate but not complete. It lists the actions and flags important safety, but leaves 'fenced' undefined and doesn't mention dry_run or the fact that delete also requires confirm per the schema.

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 62%, leaving some parameters (name, command, uuid) undocumented. The description adds value by explaining the confirm requirement for create/update, but it omits delete's confirm requirement and does not help clarify the undocumented parameters.

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 a clear list of specific actions (List, create, update, delete, view executions) tied to a specific resource (scheduled tasks on an application or service). This distinguishes it from sibling tools like manage_storage or manage_backups.

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 context for when the tool is relevant (scheduled tasks on applications/services) and provides a key usage constraint (create/update are code-execution writes requiring --allow-destructive and confirm:true). However, it does not explicitly name alternatives or state when not to use this tool.

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?

With no annotations provided, the description carries the full burden of disclosing behavior. It doesn't mention that delete is destructive, requires confirmation, or that there are dry-run capabilities. The 'fenced' term is unexplained, adding confusion rather than transparency.

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 no filler. It's appropriately short and front-loads the action verbs, making it easy to parse.

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 complex multi-action tool with 13 parameters and no output schema, yet the description is only 9 words. It doesn't clarify the 'fenced' concept, how operations differ in required fields, or what the tool returns. The minimal description is inadequate for such a complex 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?

The schema already describes all 13 parameters with 100% coverage, so the description doesn't need to repeat that. However, the description adds no additional meaning about parameter relationships or operation-specific requirements, so it stays at the baseline of 3.

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 function with the verbs 'create, update, or delete' targeting a 'Coolify server'. However, the term 'fenced' is ambiguous and no differentiation from sibling tools like create_resource or get_servers is provided, so it's not a perfect 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 provides no guidance on when to use this tool versus alternatives like create_resource or get_servers. There's no mention of required parameter combinations for each operation or any prerequisites, leaving usage context fully to the schema and agent 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?

No annotations are provided, so the description must bear the full responsibility for behavioral disclosure. It states the tool can 'delete' storage, implying destructiveness, but it does not warn about permanence, permissions, or confirm requirements. It also omits the `dry_run` option and output behavior. This is a significant transparency gap for a mutating 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 two sentences, front-loaded with the primary purpose, and the second sentence adds actionable field guidance. 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?

The tool has 9 parameters and 4 actions, no output schema, and no annotations. The description covers core purpose and create/update field requirements, but omits critical context: return values, deletion semantics, how `dry_run` works, and the distinction between `fields` and `fields_json`. This is incomplete for an agent to confidently invoke all actions.

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 reinforces key parameter requirements: 'For create/update, pass the storage fields in `fields`' and lists required and optional subfields. While this mirrors the schema's description for `fields`, it brings the information to the top level. However, it does not elaborate on `confirm`, `dry_run`, `storage_uuid`, or `instance`, which the schema partially explains. Given 56% schema coverage, the description adds some but not enough 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 opens with a clear multi-verb statement: 'List, create, update, or delete persistent volume storage for an application, database, or service.' This identifies both the actions and the resource type. However, it does not explicitly differentiate this from sibling tools like create_resource or manage_env, so it loses a point on sibling distinction.

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 some situational guidance: it notes that create requires `type` and `mount_path`, and that storage fields go in `fields`. However, it doesn't explain when to choose this tool over alternatives, nor does it mention that deletion requires confirmation (only in the schema). Usage is implied rather than explicitly laid out.

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?

With no annotations, the description carries the burden. It discloses that the action is destructive and creates billable infrastructure, along with required confirmation flags. This is significant, but it does not describe what happens after provisioning (e.g., return value, connectivity checks) or irreversible consequences beyond 'destructive'.

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 main purpose, followed by safety requirements. Every word earns its place with no 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 complex tool with 14 parameters and no output schema. The description covers the core purpose and safety gate, but it does not explain the provisioning workflow, what the response looks like, or how to use the hetzner_inventory sibling for browsing types/locations (which the schema property descriptions reference). It is minimally viable but lacks depth for such a complex operation.

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 baseline is 3. The description adds context about the confirm parameter and the --allow-destructive flag, but this is already partially captured in the schema (confirm: 'Must be true to proceed'). No new parameter semantics are added beyond what the schema provides.

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 clearly that it provisions a new server on Hetzner Cloud via Coolify, using a specific verb and resource. This distinguishes it from sibling tools like manage_server and hetzner_inventory, which handle existing servers or inventory.

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?

Implies usage for creating new servers by the phrase 'Provision a new server' and provides explicit prerequisites (--allow-destructive flag and confirm:true). However, it does not explicitly contrast with alternatives like manage_server for existing servers, so it misses the 'when-not' 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?

With no annotations, the description carries full burden, and it excels: it discloses the destructive code-execution write, the need for confirm:true, that fields are sent verbatim as the PATCH body, and that instant_deploy queues an immediate redeploy. It also highlights type-specific constraints, providing a clear behavioral profile.

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 but well-structured: it starts with the critical warning, then explains field passing, then details per-type accepted fields. It is longer than ideal but every sentence adds value. The use of lists and parentheticals aids readability. Slight deduction for length, but it is appropriately sized for the tool's complexity.

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 (multiple resource types, 7 params, no output schema), the description covers a lot: usage, field lists, and type-specific rules. However, it omits guidance for databases (the third type) and does not mention what the response looks like or expected outcomes on success/failure. These gaps prevent a perfect score.

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 covers 86% of parameters, but the description adds substantial meaning: it explains how `fields` works (verbatim PATCH body), the purpose of `fields_json` as an alternative for strict schema clients, and lists common field names with specifics (e.g., domains format, docker_compose_domains). This goes well beyond the schema's basic property descriptions.

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: 'Update configuration fields of an existing Coolify resource.' The verb 'update' and resource are specific, and it distinguishes from siblings like create_resource, delete_resource, and control_resource by focusing on configuration field updates. The resource types (applications, databases, services) are also noted.

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 explicit when-to-use guidance: requires --allow-destructive and confirm:true, and explains the destructive nature (code-execution write). It also gives detailed field usage per resource type (applications vs services), clarifies common pitfalls (e.g., use docker_compose_domains instead of domains for dockercompose apps), and notes instant_deploy behavior. This is rich guidance beyond generic usage.

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