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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it uses SSH and runs commands, which is useful, but does not disclose additional behavioral details like rate limits, required permissions, or potential command execution overhead.

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 purpose, but the list of detected items could be better structured (e.g., bullet points) for readability. No redundancy, but slight improvement possible.

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 explains what the tool inspects but fails to mention what it returns or whether any authentication/SSH setup is required. Given no output schema, additional context about the output format would be beneficial.

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% with a single optional parameter. The description's parameter mention is implicit ('app_path' inferred from 'remote directory'), but adds no new semantics beyond what the schema already 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?

The description uses a specific verb ('inspects') and resource ('remote project structure via SSH'), and lists a comprehensive set of detected items (lockfiles, package managers, etc.), clearly distinguishing it from sibling tools like 'inspect_server' which likely have different scopes.

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 explicit guidance on when to use this tool versus its siblings (e.g., 'inspect_server' or 'verify_health'). It lacks context on prerequisites, when not to use, or which alternatives to consider for specific scenarios.

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 provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds that the command is executed via SSH and is read-only, which is consistent but does not significantly expand beyond 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 a single, well-structured sentence with no unnecessary words. It is front-loaded and efficient, 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?

The description is complete for a simple read-only status check, but it lacks information about the return value or output format, which would be helpful given no output schema. Still, it adequately covers the core behavior.

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%, meaning each parameter is described in the schema. The description does not add further semantic detail beyond what the schema already provides, so a 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 specific verb 'executes' and resource 'read-only migration status command via SSH', clearly stating the purpose to check for pending migrations. It is distinct from sibling tools, which focus on deployment, server management, or other 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 implies usage for checking migration status before deployment or related actions, but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or alternatives.

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 non-destructive and idempotent behavior; the description adds valuable context about the safety threshold (>70% disk usage requirement) and specifically what is pruned (dangling Docker images, stale git branches), which goes beyond 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 a single, front-loaded sentence that conveys all key information with no unnecessary 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 description covers the main actions and conditions, including the threshold and force option. However, it does not mention return values or behavior when the threshold is not met without force, which would be helpful for a standalone tool without output 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 coverage is 100% with both parameters documented. The description does not add significant meaning beyond the schema; it only references the force parameter indirectly. 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 checks server disk usage with a specific threshold (>70%) and performs non-destructive pruning of dangling Docker images and stale git tracking branches. This specific verb and resource combination distinguishes it from siblings like inspect_server or prepare_new_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?

The description implies usage when disk usage is high (>70%) or with force flag, but does not explicitly state when to use this tool versus alternatives, nor when not to use it. There is no mention of alternatives among 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 indicate destructive and idempotent behavior. The description adds value by revealing the crucial safety check for OpenSSH before enabling the firewall, which is beyond what annotations provide. It does not contradict annotations. The description could further detail whether existing rules are preserved or overwritten.

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 extremely concise: two sentences that communicate the core purpose and the most critical safety information. No unnecessary words or repetition. The safety note is appropriately emphasized.

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 tool with no output schema and no nested objects, the description covers the main action and safety but lacks information on return values or success/failure indication. The idempotent hint and destructive hint help, but the description could state what happens when executed (e.g., 'Enables UFW after applying allowed rules').

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 baseline is 3. The description does not add new meaning beyond what the schema already provides for 'allow_nginx' and 'custom_ports'. It mentions the safety check for port 22, but that is not directly related to 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 states the tool configures UFW firewall rules safely, which clearly identifies the verb (configures) and resource (UFW firewall rules). It distinguishes from sibling tools like 'secure_env_writer' or 'setup_nginx_reverse_proxy' by focusing on firewall configuration. However, it could be more specific about the exact action (e.g., enabling the firewall after adding rules).

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 highlights a critical safety guideline: always verifying OpenSSH is allowed before enabling the firewall to prevent lockout. However, it does not explicitly state when to use this tool versus alternatives (e.g., for initial firewall setup or adding rules). The guidance is present but limited to safety 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?

The description adds behavioral context beyond annotations (e.g., pause on error instead of rolling back). No contradictions with annotations. It explains the state transition to PAUSED_AWAITING_FIX.

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 core purpose, 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?

No output schema, but the description explains key behavior. Lacks details on success state and post-execution actions, but the overall behavior is covered given sibling tools for resuming and rolling back.

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%, and the description does not add significant param-level meaning beyond what the schema already provides. Baseline score 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 specific verbs ('Executes') and resource ('deployment plan') and distinguishes itself from siblings like rollback_execution by describing the pause-on-error behavior.

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 when-to-use or alternatives are mentioned. While the context implies use after planning, the description does not guide against using this tool incorrectly or suggest siblings like plan_dynamic_deployment.

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?

Adds context beyond annotations by specifying SSH execution and state preservation, reassuring despite destructiveHint=true; does not cover failure modes or retry behavior.

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?

Single, front-loaded sentence with no wasted words; efficient and focused.

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 2 required params and no output schema, description is mostly adequate but could include example fix_command or return value hint.

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 baseline 3 applies; description adds no extra meaning to the parameters (e.g., format of fix_command).

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 (executes a diagnostic fix command via SSH), context (paused deployment), and constraints (preserves state and git status), distinguishing it from siblings like rollback_execution.

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 notes when to use ('for a paused deployment') and what it avoids ('without breaking deployment state or resetting git commit status'), but lacks explicit alternatives or when-not-to-use.

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?

Description adds behavioral context beyond annotations: it reveals that the tool connects to servers (gathers SSH credentials, OS info) and generates a local file. Annotations (readOnlyHint=false, idempotentHint=true) are consistent, but the description could be more transparent about network access requirements or potential side effects like creating files on the server. Still, it provides meaningful insight.

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?

Single sentence that conveys purpose and key actions efficiently. It is front-loaded with the verb 'Gathers' and specifies the output. Could be slightly more structured (e.g., separate sentences for input vs output), but overall concise without 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?

Given no output schema, the description covers the main output (local markdown file) and lists gathered information. However, it omits error scenarios (e.g., if server unreachable) and prerequisites (e.g., SSH key setup). For a simple documentation tool, this is mostly complete, but minor gaps remain.

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 covers both parameters with descriptions (100% coverage). The tool description adds value by explaining that app_path is auto-resolvable and that the tool gathers additional info (server IP, SSH creds, etc.) not listed as parameters. This informs the agent of what data it collects behind the scenes.

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 states the tool gathers server and config info to generate a deployment runbook markdown file. It uses specific verbs ('gathers', 'generate') and identifies the resource (DEPLOYMENT_RUNBOOK.md). The purpose is distinct from sibling tools like plan_dynamic_deployment or setup_nginx_reverse_proxy, which perform actual deployment actions rather than documentation.

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 mentions 'for manual ops and handovers', indicating when to use the tool. However, it does not explicitly state when not to use it or mention alternatives among the sibling tools. The guidance is implied but lacks explicit differentiation (e.g., 'for automated deployment use plan_dynamic_deployment').

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 read-only and idempotent behavior; the description adds valuable context about dynamic SSH access and fallback, exceeding the annotation-provided information.

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, no wasted words, front-loaded with the primary action and resource. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read operation with good annotations, the description is nearly complete. It covers the methodology (SSH) and edge case (fallback). The lack of output schema is acceptable.

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 covers the parameter fully; the description adds minimal extra context by mentioning 'VPS project directory', but does not provide semantics beyond the schema's description.

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 (reads), the resource (.env.example), the method (via SSH), and the fallback behavior, distinguishing it from write tools like secure_env_writer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing a secure environment template, but does not explicitly mention when not to use or alternative tools, despite the presence of sibling tools like secure_env_writer.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about SSH interaction and checks performed, but doesn't detail output format. Overall complements annotations well.

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?

Single sentence, front-loaded with 'Safely inspects'. No wasted words, directly conveys purpose. Excellent conciseness.

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?

Describes the inspection actions (VPS state, runbook existence, deployment history) but omits specifics on output format or return structure. Adequate for a simple read-only tool with no output 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?

No parameters exist, so the description need not add parameter info. With 100% schema coverage and zero params, baseline 4 is appropriate. The description doesn't discuss parameters, which is fine.

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 inspects VPS server state via SSH and checks local project runbook existence and deployment history. This is specific and distinguishes it from sibling action-oriented 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?

No guidance on when to use this tool versus alternatives like verify_health or diagnose_and_fix. The description lacks when-to-use, when-not-to-use, or explicit alternatives.

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 idempotent and read-only behavior; the description adds specific target OS distributions and components. It confirms the tool generates a plan rather than mutating state, which aligns with annotations. It does not, however, describe the plan output format or any error conditions.

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, complete sentence of 20 words, front-loading the primary action and efficiently conveying the tool's purpose, scope, and property of idempotency. No unnecessary words or padding.

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 tool with 3 optional parameters and no output schema, the description adequately covers the core behavior and expected output (a provisioning plan). It lacks detail on the plan's format or how to execute it, but given the context, it provides sufficient completeness for an agent to understand and use the 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% with each parameter described. The tool description mentions 'dynamic version' for Node.js but adds no further details on parameter interactions or defaults beyond what the schema provides. Therefore, it meets the baseline for a fully described 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 generates an idempotent provisioning plan for installing Node.js, PM2, Docker Engine, and Docker Compose across Debian, RHEL, and Alpine Linux. It uses a specific verb 'generates' and identifies all target resources, making it distinct from sibling tools like plan_docker_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 provides context on what the tool does but does not explicitly state when to use it versus alternatives, nor does it include any prerequisites or conditions. For instance, it doesn't indicate that this should be used before deployment planning tools.

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 aligns with annotations (readOnly, idempotent, non-destructive) by stating it does not execute. It adds context about safety and command generation but lacks details like output format or side effects.

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 (two sentences) and front-loaded with the core purpose. No extraneous information.

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 planning tool with good annotations and full schema, the description covers the essential safety constraint. Minor gap: no mention of what the output looks like, but not critical given the tool's nature.

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 parameters are fully described in the schema. The description adds no extra semantic value 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?

The description clearly states it plans a safe Docker Compose deployment and generates commands. It distinguishes itself from execution tools like confirm_execution by explicitly noting it does not execute.

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 indicates this tool should be used before confirm_execution to plan deployment. However, it does not compare to sibling tools like plan_dynamic_deployment, so guidance on when to use this specific tool is implicit but not exhaustive.

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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds detail about the analysis inputs (git diffs, schema, migrations) and conditional nature, but does not elaborate on outcome format, potential external calls, or runtime behavior beyond what annotations imply.

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, clear sentence that front-loads the purpose. However, it could be slightly restructured for readability, e.g., by listing key analyses separately. Still, it is concise without 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?

Given the tool's complexity (9 parameters, no output schema), the description covers core purpose but does not explain what a 'production-first conditional deployment plan' entails, nor does it address the absence of output schema or integrate with sibling tool usage. It is minimally 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 description coverage is 100%, so the schema already documents each parameter's meaning. The description does not add parameter-level information beyond what is in the schema, so 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 specifies the tool's action: analyzing git diffs, dependency changes, schema updates, and pending migrations to generate a production-first conditional deployment plan. It distinguishes from siblings like plan_docker_deployment by focusing on dynamic, change-based planning.

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 provide explicit guidance on when to use this tool versus alternatives. It implies usage for deployment planning but lacks when-not or alternative suggestions, leaving the agent without clear selection criteria among multiple deployment and diagnostic 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 indicate read-only, idempotent, non-destructive behavior. The description adds context: it generates a plan based on OS detection, not actually executing actions. This clarifies that the tool does not modify state, consistent with annotations. No contradictions. The description adds useful behavioral specifics beyond 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 a single, well-structured sentence that front-loads the main action ('Generates a multi-OS provisioning plan') and then details specific parts. No redundant words; every part adds value. Ideal length for a tool with no parameters.

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 zero parameters, the description covers the tool's purpose and supported OS. However, it does not specify the format of the generated plan (e.g., text summary, step list) or how the plan is returned. This minor gap is acceptable for a simple planning tool, but slightly incomplete for an agent that might need to interpret the output.

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 has zero parameters, so schema coverage is 100%. Per guidelines, baseline is 4. The description does not need to add parameter info. It correctly implies the tool operates based on detected OS with no required 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 tool's function: generating a multi-OS provisioning plan. It specifies the actions (update system packages, install core utilities) and supported OS distributions (Ubuntu, Debian, RHEL, CentOS, Alpine). This distinguishes it from sibling tools like 'install_runtimes' or 'configure_firewall' which focus on specific tasks rather than generating a comprehensive plan.

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 initial server setup, but does not explicitly state when to use vs. alternatives (e.g., 'inspect_server' for inspection, 'confirm_execution' for execution). However, the context of 'prepare_new_server' and siblings suggests it's intended for planning before execution. The lack of explicit exclusions is balanced by the tool's self-explanatory purpose.

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 destructiveHint=true and readOnlyHint=false. The description adds the context of skipping already completed steps and executing remaining, which provides behavioral nuance beyond 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?

Single sentence of 18 words that front-loads the core action. Every part is necessary; zero 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 simple resume operation with two parameters and annotations present, the description adequately explains the core behavior. However, it lacks guidance on how to obtain the plan_id or how it differs from 'confirm_execution'.

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 covers 100% of parameters with descriptions. The tool description itself adds no additional semantic value beyond what the schema already provides, so 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 the verb 'resumes' and the resource 'paused deployment plan', and adds specific behavior: skipping completed steps and executing remaining. This distinguishes it from siblings like 'confirm_execution' or 'rollback_execution'.

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 paused plans but does not explicitly state when to use this tool versus alternatives like 'confirm_execution' or 'rollback_execution'. No when-not-to-use guidance is 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 indicate destructiveHint=true and openWorldHint=true. The description adds specifics: it triggers 'git reset, service reload', giving concrete behavioral detail beyond the annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that conveys all essential information without unnecessary words. Every part 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?

The description covers purpose, usage conditions, and key actions. While no output schema exists, the tool is simple and the description suffices. Minor omission: could mention post-rollback state, but not critical.

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% and the description does not add further meaning to the parameters (plan_id and reason) beyond what the schema already provides. 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 tool aborts a paused or failed deployment plan and triggers rollback. It uses specific verbs ('aborts', 'rollback') and names the resource ('deployment plan'), distinguishing it from siblings like resume_execution.

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 specifies when to use: for paused or failed deployment plans. It does not explicitly exclude other situations or mention alternatives, but the context is clear enough that it's for rollback scenarios.

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 reveals key behaviors beyond annotations: path normalization via path.resolve, heredoc writing to prevent shell expansion, zero-knowledge output, and blocking of system paths. Annotations already indicate it is write-only (readOnlyHint false) and destructive (destructiveHint true), so description adds valuable context without 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 concise and well-structured: a clear initial sentence followed by bullet points listing security guarantees. Every sentence adds value, 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 the complete input schema, annotations, and absence of output schema, the description fully covers what the tool does, its security measures, and its behavior. It is sufficient for an agent to correctly invoke the tool and understand the risks.

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?

Input schema coverage is 100%, with both parameters well-described in the schema. The description adds overall context but does not enhance parameter semantics beyond what the schema already provides (e.g., absolute path example). 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 it 'Writes environment variables to a .env file on the remote server via SSH after path normalization.' This is a specific verb and resource, and it distinguishes itself from the diverse sibling tools which cover server inspection, deployment, and 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?

While the description does not explicitly list when to use or alternatives, the sibling tools are very different (e.g., inspect_server, rollback_execution), making it clear this is the tool for writing environment files. The security guarantees implicitly guide usage, but no explicit when-not guidance is 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?

Adds context about domain verification and adaptive behavior beyond annotations, but does not disclose the destructive nature (despite destructiveHint=true) or what gets overwritten. The description gives some transparency but misses key behavioral details.

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?

Single sentence with under 20 words, front-loaded with verb and resource. Concise but slightly dense; could be structured for better clarity. Still 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?

Minimal description for a 4-parameter tool with no output schema. Leaves gaps: what is 'adaptive'? What happens if A-record check fails? No mention of return values or effects. Adequate but not comprehensive.

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 description adds no additional parameter-specific meaning. Baseline score of 3 is appropriate as the tool's purpose is clear but parameters rely solely on schema 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?

Clear verb ('configures') and specific resource ('Nginx reverse proxy or static web server block'). Includes a prerequisite (domain A-record verification) and distinguishes from sibling tools like configure_firewall or setup_ssl_certbot. Effectively communicates the tool's 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?

Implies usage context (after domain verification) but provides no explicit guidance on when to use vs alternatives. No mention of when-not or other sibling tools. Adequate but lacks depth.

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 adds valuable behavioral context beyond annotations: it generates a 2-step plan, uses OS-specific package mapping, and tests auto-renewal. This contrasts with the destructiveHint annotation by clarifying it is a planning tool, not directly mutating. No contradiction with 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?

Two sentences, concise and front-loaded with the core purpose, followed by key capabilities. No redundant information.

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 simplicity (0 required params, no output schema), the description covers essential aspects: plan generation, OS mapping, and auto-renewal testing. It is clear and sufficient for an agent to understand what the tool does, though it lacks details on how to execute the generated plan.

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 described in the input schema (100% coverage), including fallback to .devops-mcp.json. The description does not add new semantic information about parameters, meeting the baseline expectation.

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 it generates an execution plan for installing Certbot and configuring Let's Encrypt SSL for Nginx, specifying the verb 'generates' and the resource 'SSL certificate for Nginx using Certbot'. However, it does not explicitly distinguish itself from sibling tools like setup_nginx_reverse_proxy, which is a separate but related task.

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 or prerequisites. The description implies it is for planning an SSL setup, but does not state conditions or provide 'when not to use' 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing the use of SSH and curl, and that success requires HTTP 200. This provides good behavioral context beyond 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 a single, well-structured sentence that conveys all necessary information without wordiness. Every word 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 no output schema, the description covers the return condition (success only if HTTP 200). It lacks details on error handling (e.g., timeouts, non-200 responses) but is sufficient for a simple health check tool with 2 optional parameters.

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 does not add extra meaning beyond the schema; it mentions 'HTTP endpoint' which aligns with the parameters but provides no additional detail on format or constraints.

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 action: executing curl via SSH to verify HTTP endpoint status, with explicit success criterion of HTTP 200. It distinguishes itself from sibling tools like inspect_server or view_app_logs by specifying the exact method and 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 guidance on when to use this tool versus alternatives. The description lacks explicit context for when it is appropriate, when not, or reference to sibling tools.

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, idempotentHint, destructiveHint, so the safety profile is clear. The description adds that logs are retrieved via PM2 or Docker on a remote server, but does not elaborate on potential timeouts, connection issues, or return behavior beyond what annotations 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?

The description is a single, well-structured sentence that is concise and front-loaded with the action ('Retrieves...'). Every word is meaningful, with no 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?

The description covers the tool's basic purpose and execution methods, but does not describe the return format (e.g., array of log lines) or potential limitations. Given no output schema, this information 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%, so the schema fully documents all parameters (app_name, mode, lines). The description adds no additional meaning for parameters, earning 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 retrieves recent application log lines via PM2 or Docker Compose on a remote server. The verb 'retrieves' and resource 'log lines' are specific, and the tool is distinct from siblings like 'verify_health' or 'inspect_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?

The description provides no explicit guidance on when to use this tool versus alternatives. The 'mode' parameter in the schema offers some context, but the description itself lacks any usage context or exclusions.

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