openvpn_sessions

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

The [READ] prefix explicitly signals this is a read-only operation, which is valuable given no annotations are provided. However, beyond the read indication, no behavioral details are disclosed — no mention of refresh behavior, staleness of data, or whether it requires admin privileges. The [READ] tag adds value, but for a tool with zero annotations, the description carries more burden than it fully discharges.

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 short lines for the purpose plus a clear parameter note. The [READ] prefix is a useful front-loading device. No wasted words. Slightly lower than 5 because the Args formatting is a bit terse but functional.

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 single-optional-param read-only status tool, the description is reasonably complete — it covers the purpose, the [READ] behavior, and the sole parameter. However, with no output schema and no annotations, it doesn't describe the return format or data freshness, leaving some ambiguity. Given the tool's simplicity, this is adequate but not exceptional.

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

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

The description explains the single 'target' parameter ('Firewall target name from config; omit for the default'), which is meaningful context beyond the schema. However, schema description coverage is 0%, so the schema provides no description at all; the description's explanation is the only documentation. Given only one optional param fully explained, a 3 is fair — it does add value but the coverage baseline would suggest more effort is needed.

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

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

The description clearly states the verb (read/list) and resource (OpenVPN sessions/connected clients) with parenthetical detail on what's returned (name, address, bytes). It's easily distinguished from siblings like wireguard_status and ipsec_sas which cover other VPN protocols. However, it doesn't explicitly differentiate from those sibling VPN status tools, slightly lowering it.

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 context (checking connected OpenVPN clients) but provides no explicit guidance on when to use this vs alternatives. Among siblings, wireguard_status, ipsec_sas, and interface_status exist but no exclusions or comparisons are given. The [READ] prefix does signal it's a safe diagnostic read, but no explicit when-to-use advice.

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