Server Quality Checklist

Tool Scores

• create_clientA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of disclosing behavior. It mentions that keys and IPs are auto-generated by wg-easy and that the new client ID is returned. However, it does not disclose potential side effects, permission requirements, or whether the client is immediately active.

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

  Conciseness5/5

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

  The description is two concise sentences that front-load the core action and provide useful follow-up context. No unnecessary words or repetition.

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

  Completeness4/5

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

  The description is sufficient for a simple creation tool with full schema coverage. It explains the core behavior, auto-generation, and return value. It lacks optional details like default state or uniqueness constraints, but these are not critical for basic usage.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema fully describes both parameters (name required, expiresAt optional) with descriptions, so baseline is 3. The description adds no additional parameter-level meaning; it only notes that keys/IPs are generated, which is implied by the tool's purpose.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: creating a new WireGuard client. It specifies the action (create), the resource (WireGuard client), and additional outcomes (generated keys/IPs, returns client ID). The verb 'create' distinguishes it from sibling tools that list, get, update, enable, disable, delete, or fetch configs.

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

  Usage Guidelines3/5

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

  The description implies usage when a new client needs to be added, but it does not explicitly state when to use this tool versus alternatives like update_client or enable_client. It provides no exclusion criteria or conditional guidance.

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

• get_clientA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint: true, covering the safety profile. The description adds the scoping promise of 'full details' and 'single', but does not disclose return format, pagination, error behavior, or authentication requirements, providing limited additional 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.

  Conciseness5/5

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

  The description is a single sentence of eight words, front-loaded with the verb 'Get', and contains no filler words. Every word contributes to understanding the tool's purpose.

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

  Completeness4/5

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

  For a simple single-parameter read tool with a read-only annotation, the description is mostly adequate. It clearly states the operation and scope, though 'full details' is vague and there is no output schema to define the return structure. Still, the context is sufficient for an agent to select the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The only parameter clientId is fully described in the schema with a type, range, and a cross-reference to list_clients, giving 100% schema coverage. The description adds no parameter-specific semantics, so baseline 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses the specific verb 'Get', identifies the resource as 'WireGuard client', and specifies scope with 'single', which clearly distinguishes it from list_clients and other get variants like get_client_config or get_client_qrcode.

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

  Usage Guidelines3/5

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

  The description implies usage for fetching a single client's details via the word 'single', but it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites beyond the schema's reference to list_clients.

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

• get_client_configA
  3.9/5.0
  Behavior4/5

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

  The annotation already declares readOnlyHint=true, but the description adds critical security context: the output contains the client private key and should be treated as secret. It also discloses the output format (wg .conf), going beyond the structured annotation.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core function and a concise security warning. Every word earns its place with no redundancy.

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

  Completeness5/5

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

  The tool has a single parameter, read-only annotation, and no output schema. The description explains the return format ('wg .conf') and adds the vital sensitivity caveat, covering all essential context for correct use.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema fully describes clientId with 'Numeric ID of the client (see list_clients)', so baseline 3 applies. The description adds no extra parameter meaning, but none is needed.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Get') and resource ('WireGuard configuration file (wg .conf format)') clearly distinguishing it from siblings like get_client_qrcode or get_client. It states exactly what is returned.

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

  Usage Guidelines2/5

  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 vs alternatives. The description does not mention get_client_qrcode, generate_one_time_link, or other related tools, so an agent receives no help choosing among them beyond the tool's name.

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

• enable_clientA
  4/5.0
  Behavior3/5

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

  The annotations already declare idempotentHint=true, so the description does not need to restate that. The description adds minimal behavioral context beyond the annotation, such as the effect of enabling the client. It does not contradict the annotations, but also does not disclose additional details like what happens if the client is already enabled.

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

  Conciseness5/5

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

  The description is a single, concise sentence that directly states the tool's purpose. It contains no fluff or redundant information, making it optimally concise and well-structured for quick agent comprehension.

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

  Completeness4/5

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

  The tool is simple with one parameter and no output schema, and the description combined with the idempotent annotation provides sufficient context for an agent to understand the operation. However, it does not mention return value or behavior when already enabled, which would be useful but is not critical given the idempotent annotation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema fully documents the single parameter (clientId) with a description and constraints, achieving 100% schema coverage. The description itself adds no parameter-specific information, so it relies on the schema as baseline. No further semantic enrichment is provided.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb 'Enable' with a clear resource 'WireGuard client' and adds the purpose 'so it can connect again', which clearly differentiates it from siblings like disable_client or create_client. It also implicitly indicates a state transition from disabled to enabled.

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

  Usage Guidelines4/5

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

  The phrase 'so it can connect again' provides clear context that this tool is for re-enabling a previously disabled client, which distinguishes it from create_client or update_client. However, it does not explicitly state when not to use it or name alternatives, so it misses the top score for explicit exclusions.

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

• update_clientA
  4/5.0
  Behavior4/5

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

  The description discloses a critical behavioral trait: partial update semantics. 'Only the provided fields are changed; all other settings are preserved' prevents an agent from assuming a full replacement. However, with empty annotations, the description still lacks details about error handling, permissions, or response format, though the disclosed merge behavior is valuable.

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

  Conciseness5/5

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

  The description is two sentences with no filler. The first sentence states the action, and the second clarifies the update behavior. Front-loaded and highly efficient.

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

  Completeness4/5

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

  For an 11-parameter tool, the schema provides thorough per-parameter descriptions, and the description adds the crucial merge semantics. While no output schema is present, the tool's behavior is sufficiently defined for correct invocation. Minor gaps like error conditions or parameter interactions remain, but overall it is complete enough.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the schema already documents all 11 parameters, including descriptions. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action ('Update a WireGuard client') with a specific verb and resource, distinguishing it from sibling tools like create_client or delete_client. It also adds a scope clarification (only provided fields are changed), reinforcing the purpose.

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

  Usage Guidelines3/5

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

  The description implies usage by naming the operation, but it does not explicitly state when to use this tool versus alternatives like enable_client or create_client. No exclusions or alternative references are provided, so the guidance is only implicit through the tool name.

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

• generate_one_time_linkA
  4.2/5.0
  Behavior4/5

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

  The description discloses the one-time nature, the server-side requirement (WG_ENABLE_ONE_TIME_LINKS), and a critical security behavior: the link grants unauthenticated access to the full config. This is valuable beyond the empty annotations, but it doesn't cover error handling or expiration details beyond 'one-time'.

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

  Conciseness5/5

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

  Two concise sentences front-load the purpose and then add the requirement and security warning. No filler or redundancy.

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

  Completeness4/5

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

  For a single-parameter tool with no output schema, the description adequately covers purpose, usage, and a critical security caveat. It lacks explicit error behavior when the environment flag is disabled, but this is minor given the simplicity.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema fully documents clientId with a clear description ('Numeric ID of the client (see list_clients)'). The description adds no additional parameter context, so the baseline score of 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Clearly states the tool generates a one-time download link for a client configuration, distinguishing it from sibling tools like get_client_config (which returns the config directly) and get_client_qrcode (which generates a QR code). The verb 'generate' and resource 'one-time download link' are specific.

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

  Usage Guidelines4/5

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

  Provides context that the link is meant to be shared with end users and requires WG_ENABLE_ONE_TIME_LINKS to be enabled. It implicitly suggests using this instead of direct config retrieval when sharing externally, though it doesn't explicitly name alternative tools.

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

• get_server_infoA
  4.2/5.0
  Behavior4/5

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

  The readOnlyHint annotation already signals a read-only operation, and the description adds useful behavioral context by stating that secret fields (private keys, passwords) are redacted. This goes beyond the annotation and gives the agent important safety information.

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

  Conciseness5/5

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

  The description is concise and front-loaded, consisting of two sentences that first state the main purpose and then add the redaction behavior. Every sentence earns its place with no wasted words.

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

  Completeness4/5

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

  For a simple getter with no parameters and no output schema, the description covers the key information categories (release/update status, settings, interface config) and the redaction behavior. It is slightly limited in not detailing the return format, but this is a minor gap for a tool of this simplicity.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters, so there is no parameter semantics to clarify. The description doesn't need to add anything here, which meets the baseline of 4 for parameter-less tools.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: to get information about the wg-easy instance, specifying categories such as release/update status, general settings, and WireGuard interface configuration. This distinguishes it from the sibling tools, which are all client-focused (list_clients, create_client, etc.).

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

  Usage Guidelines3/5

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

  The description implies it is for server-level information, but it does not explicitly state when to use this tool over alternatives or mention any exclusions. Usage guidance is therefore implied rather than stated.

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

• list_clientsA
  4.2/5.0
  Behavior4/5

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

  The readOnlyHint annotation already indicates a safe read operation, and the description adds meaningful context by specifying the returned fields (status, addresses, traffic statistics) and that it lists all clients. It does not overstate behavior or contradict annotations.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that starts with the action and includes all essential information without unnecessary words. It wastes no space and is easy to parse.

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

  Completeness4/5

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

  For a relatively simple list operation, the description plus schema and readOnlyHint provide enough context. It states the scope ('all clients') and the key return contents. A minor gap is the absence of a mention of response shape or array format, but this is not critical given no output schema and the straightforward nature of the tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, with both 'sort' and 'filter' clearly documented in the input schema. The tool description adds no additional parameter-level detail, but the schema fully covers semantics, so the baseline score of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('List') and clearly identifies the resource ('all WireGuard clients of the wg-easy instance') and the information returned (status, addresses, traffic statistics). This effectively distinguishes it from sibling tools like get_client, create_client, and delete_client.

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

  Usage Guidelines4/5

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

  The phrase 'List all WireGuard clients' clearly conveys when to use this tool: when you need a complete overview of clients rather than a single client (get_client) or a mutating operation. However, it does not explicitly mention alternative tools or exclusion criteria, so it stops 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.

• disable_clientA
  4.3/5.0
  Behavior4/5

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

  With idempotentHint annotation present, the description adds value by detailing the non-destructive nature ('keeps its configuration') and the effect ('can no longer connect'), going beyond the annotation. It omits active connection handling but remains sufficient given the annotation coverage.

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

  Conciseness5/5

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

  Two sentences, direct and free of fluff. The purpose and key behavioral constraint are front-loaded, with no unnecessary words.

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

  Completeness5/5

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

  Simple one-parameter tool with good schema and annotation coverage. Description covers purpose, effect, and non-destructive behavior; no output schema exists. Adequate for tool selection and invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Input schema covers 100% of parameters, with clientId described as 'Numeric ID of the client (see list_clients).' The description adds no parameter-level detail, so the baseline score of 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description states 'Disable a WireGuard client' with a specific verb and resource. It further clarifies the client 'keeps its configuration but can no longer connect,' distinguishing it from delete_client and clearly opposing enable_client.

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

  Usage Guidelines4/5

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

  Provides clear context: it disables access while preserving configuration, implying a temporary revocation use case. However, it does not explicitly name alternatives like delete_client or enable_client, so exclusions are implicit rather than stated.

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

• get_client_qrcodeA
  4.5/5.0
  Behavior5/5

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

  The description discloses that the QR code encodes the client private key and explicitly warns to treat it as a secret, providing critical security context beyond the readOnlyHint annotation. It also specifies the output format as SVG markup, which is useful behavioral information.

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

  Conciseness5/5

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

  The description is two concise sentences: the first states the purpose and output format, the second delivers a necessary security warning. Every word adds value, with no redundancy.

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

  Completeness5/5

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

  For a single-parameter read-only tool with full schema coverage, the description adequately covers the essential context: what it returns (SVG QR code), why it is used (mobile app scanning), and a critical sensitivity warning. The lack of an output schema is mitigated by the explicit mention of the return format.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The only parameter, clientId, is fully described in the schema with type, range, and a reference to list_clients. The description adds no extra parameter semantics, so the baseline of 3 is appropriate given 100% schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states it retrieves the client configuration as a QR code in SVG markup for use with the WireGuard mobile app. The specific verb 'Get' plus the resource 'client QR code' distinguishes it from sibling tools like get_client_config, which returns plain configuration text.

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

  Usage Guidelines4/5

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

  The phrase 'for scanning with the WireGuard mobile app' provides clear context on when to use this tool. However, it does not explicitly mention alternatives or state when not to use it, e.g., versus get_client_config, so it slightly misses the top score.

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

• delete_clientA
  4.7/5.0
  Behavior5/5

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

  The description goes well beyond the destructiveHint annotation by explicitly stating the irreversible consequences: 'This is irreversible: the client loses VPN access and its keys cannot be restored.' It also reveals the behavioral nuance of requiring a confirmation token, which is not available in annotations. This fully informs the agent of the tool's operational traits.

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

  Conciseness5/5

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

  The description is three sentences, each earning its place: purpose, irreversibility, and the confirmation flow. It is front-loaded with the primary action and contains no filler or redundant phrases. This is an excellent balance of completeness and brevity.

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

  Completeness5/5

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

  Given the lack of an output schema, the description adequately covers all necessary behavioral context for a destructive operation. It explains the irreversible nature, the confirmation token workflow, and the impact on the client. The tool's complexity is fully addressed without needing to describe return formats.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema provides 100% coverage of both parameters (clientId and confirmToken) with their own descriptions. The tool description adds extra semantics by explaining why confirmToken is needed and its role in the two-step confirmation process. While the schema alone would be sufficient, the description enriches the understanding of the parameter behavior.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's primary function: 'Permanently delete a WireGuard client.' This is a specific verb+resource combination that fully distinguishes it from sibling tools like get_client, update_client, or disable_client. The title reinforces the action, and the description adds critical scope (permanent deletion, loss of VPN access).

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

  Usage Guidelines4/5

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

  The description provides clear usage context by explaining the two-step confirmation flow: 'The first call returns a short-lived confirmation token; ask the user for confirmation, then call again with confirmToken.' This tells the agent when to call again and how to use the token. However, it does not explicitly mention alternatives (e.g., when to prefer disable_client over delete_client), so it lacks explicit when-not conditions.

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