Set network VPN peer egress

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

Annotations declare destructive/idempotent/openWorld, and the description adds substantially beyond them: required scopes (networking:read vs networking:manage, with full/read defaults not applying), backend enforcement of ownership/feature/2FA, the fact that acceptance is pending rather than proof of connectivity, and precise polling semantics for in_progress/reason_kind. It also prescribes idempotency-key reuse and a no-auto-retry rule on transport uncertainty.

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?

Purpose and auth are front-loaded, which is good, but the polling paragraph is a dense run-on that mixes waiting behavior, reason_code interpretation, failure definition, and recovery guidance. The content is defensible but would read better split into shorter, clearly scoped sentences.

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?

With no output schema, the description carries the return-handling burden and does so by explaining that the returned operation/resource must be polled on in_progress with next_check_seconds, and how to classify failure versus waiting. Combined with scope and recovery guidance, an agent has enough to call and follow up correctly, though expected_generation remains unexplained.

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 coverage is 60%, and the description fleshes out policy intent (private-only vs inherited NAT vs advertised chosen exit, client-route opt-in) but never explains expected_generation's optimistic-concurrency role or the destinations/dns fields. The mode semantics are the main added value; the remainder leans on the schema.

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 first sentence names a specific verb (Set) and resource (a VPN peer's egress policy) and enumerates the three modes, which cleanly separates it from siblings like set_network_vpn_peer_grants, set_network_routed_egress, and the read-only get_network_vpn_egress_options. It says 'a device's' rather than 'a peer's', a minor slippage, but the resource is otherwise unambiguous.

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?

It gives real preconditions: read egress options first, Internet routing needs explicit client_route_opt_in plus applied qualification, and inspect current capabilities and owned state before changing. It stops short of naming the sibling read tool (get_network_vpn_egress_options) explicitly, so the agent must infer the lookup target.

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