Set network VPN peer grants

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

Goes well beyond the annotations: it warns this replaces the entire list (matching destructiveHint), explains the empty-list deletion case, the routes_update consequence on AllowedIPs, backend ownership/feature/2FA enforcement, and that 'an accepted operation is pending, not proof of connectivity'. It then discloses the full asynchronous lifecycle (in_progress, reason_code/reason_kind, next_check_seconds) and the idempotency/recovery contract ('reuse only the original key and unchanged request; never automatically retry'), which annotations alone cannot 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?

Front-loaded with the mutation semantics, then layered prerequisites, then polling/recovery rules. Every sentence carries operational weight (permissions, approval, polling interpretation, retry policy), but the polling paragraph is long and the guidance about preserving reason_code and the idempotency key restates the same recovery idea more than once.

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 destructive, open-world, asynchronous mutation with no output schema and only 60% parameter coverage, the description supplies what the structured fields do not: auth scopes, approval workflow, post-change customer action (routes_update), and how to interpret the pending operation until in_progress is false. Nothing essential to calling this correctly is missing.

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 60%; peer_id, gateway_id and idempotencyKey are documented in-schema, while grants and expected_generation are not. The description compensates for grants ('Empty list removes server grants') and partially for the key ('preserve it and the unchanged body'), but expected_generation is only obliquely gestured at via 'use gateway generation' and never explained as an optimistic-concurrency token.

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 opening sentence states a specific verb and resource: 'Replace the device's complete reachable-server list when standalone VPN is available,' which tells the agent this is a full-list mutation of a VPN peer's grants, not an additive one. It also clarifies the semantics of the payload ('Empty list removes server grants'). It stops short of naming the neighboring *egress* operation, so the agent must infer the grants-vs-egress distinction itself.

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?

Gives concrete preconditions (standalone VPN must be available, 'Read current capabilities and owned resource state first', 'obtain approval for the exact change') and the exact permission scopes required (networking:read vs networking:manage, with the warning that 'full/read defaults do not grant networking'). It does not explicitly route the agent away from sibling tools such as set_network_vpn_peer_egress or create_network_vpn_peer, so there is no explicit when-not guidance.

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