delete_vpn_server

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

With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly warns 'Permanently removes VPN server' and 'Connected clients will lose access immediately,' covering irreversibility and immediate impact. It does not mention permissions or rollback, but it effectively discloses the critical characteristics of this destructive 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 efficient and well-structured: a warning is front-loaded, followed by a compact parameter list. Every sentence adds value, and there is 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?

For a simple destructive action with three required parameters and an output schema (not shown), the description covers purpose, permanence, immediate effect, and parameter meanings. The main gaps are absence of explicit alternative routing and the unexplained necessity of host/site context, but the core information needed to invoke the tool correctly is present.

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

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

Schema description coverage is 0%, so the description must compensate. It does by explaining all three parameters: host as console name/ID/composite ID (MAC:numericId), site as site name/ID, and server_id as VPN server ID. This adds meaning beyond the bare string type. However, it doesn't clarify why host and site are required when deleting 'by ID' or how they relate to server_id.

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 exact action and target: 'Delete a VPN server by ID.' The warning reinforces the destructive nature, and the resource is explicitly identified as a VPN server. This clearly distinguishes it from related VPN server tools like list_vpn_servers, get_vpn_server, create_vpn_server, and update_vpn_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 you want to permanently remove a VPN server—but it does not explicitly state when to use this vs alternatives such as update_vpn_server for disabling or unconfiguring. No 'when not to use' or alternative routing is provided; the guidance is left to inference.

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