Get network VPN peer recipe

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

Annotations already flag readOnly/idempotent/non-destructive, and the description adds material context beyond them: the returned recipe contains a literal {{PSK}} placeholder and never the secret, which must be substituted outside MCP. It also discloses authorization scopes, backend ownership/feature/2FA-lock enforcement, and what the tool does not do.

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?

Six tight sentences, front-loaded with the core action and scoping, with defaults and refusals following logically. Slight redundancy remains — the 'networking:manage for changes' clause is boilerplate for a read-only tool and adds noise.

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 still characterizes the return (a vendor-specific recipe with a {{PSK}} placeholder), covers prerequisites, defaults, refusal cases, and auth requirements. Nothing an agent needs to invoke it 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 coverage is 75%, and the description still adds defaulting behavior the schema lacks: omitting vendor falls back to the site's saved vendor, and lang defaults to en. It also ties vendor IDs to the ipsec_vendors catalog and peer/gateway IDs to owned networking resources, giving real semantic value.

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?

States a precise verb and resource: read router setup instructions for one owned IPsec IKEv2 site. It is clearly distinguished from adjacent tools like take_network_vpn_peer_config (config payload) and get_network_appliance_capabilities (capability catalog), so an agent can pick correctly without opening schemas.

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 explicit conditions: vendor overrides the site's saved vendor only when supplied, lang defaults to en, and it names the cases when the call is refused (devices, WireGuard sites, revoked sites). It also frames the boundary — the tool does not enable IPsec or establish deployment/interoperability — and points at reading gateway capabilities first.

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