update_wireguard_peer

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

Annotations already declare idempotent and non-destructive behavior, so the description adds value with details on clearing fields and peer_id format. However, it does not disclose whether updates are partial (only provided fields) or full replacements, nor does it mention all updatable fields like comment and endpoint_port.

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

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

The description is compact and front-loaded: a single clear purpose statement followed by focused parameter notes. Every sentence adds value, no fluff or repetition.

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

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

For a 9-parameter mutation tool with no schema descriptions, the description is only partially complete. It explains key parameters well but omits endpoint_port, comment, device, and the semantics of partial updates. This leaves room for incorrect invocation without further research.

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?

With 0% schema description coverage, the description compensates well for several parameters: peer_id ('*N' format), allowed_address (CIDR examples), persistent_keepalive (seconds as string), and clearing endpoint_address/preshared_key. It misses format guidance for endpoint_port and mapping for disabled, but the essential tricky parameters are covered.

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 explicitly states the action ('Updates'), the resource ('existing WireGuard peer'), and the specific attributes that can be modified (allowed addresses, endpoint, keepalive, enabled state). This clearly distinguishes it from sibling tools like create/remove/list peers.

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

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

The description clearly implies this tool is for modifying existing peers, not creating new ones, and provides practical formatting guidance for several parameters. However, it does not explicitly compare with sibling tools like enable_wireguard_peer or disable_wireguard_peer, which could also alter the enabled state.

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