create_ipsec_phase2_encryption

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description 'Create an IPsec Phase 2 encryption entry' adds no behavioral context beyond that. It does not mention that parameters like dhgroup, prf_algorithm, and hash_algorithm are accepted for compatibility but not sent, nor that changes might need to be applied with apply_ipsec_changes to take effect.

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 a single sentence, which is concise and front-loaded. However, it leans toward under-specification; it essentially restates the tool name with minimal added value. For a tool with 7 parameters and behavioral nuances, this is not sufficiently informative for concise-sized, but it is still grammatically compact.

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?

Given the tool's complexity (7 parameters, ignored compatibility fields, parent_id dependency, output schema present), the one-sentence description is insufficient. It does not explain the object hierarchy (Phase 2 encryption entry belongs to a Phase 2), the fact that some parameters are accepted but not sent, or that apply_ipsec_changes may be required. The output schema may cover return values, but the description leaves important operational context unaddressed.

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 100%, so every parameter already has a detailed description, including notes about compatibility-only fields. The tool description adds no parameter-specific information, but per the guideline, when schema coverage is high, baseline 3 is appropriate.

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 uses the specific verb 'create' and identifies the resource as 'an IPsec Phase 2 encryption entry,' making the core purpose clear. It distinguishes itself from sibling tools like search_ipsec_phase2_encryptions, update_ipsec_phase2_encryption, and delete_ipsec_phase2_encryption through the verb 'Create,' and from create_ipsec_phase2 by specifying 'encryption entry' rather than the parent Phase 2 object. However, it does not explicitly highlight this distinction from create_ipsec_phase2, so it is not a perfect 5.

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 provides no guidance on when to use this tool versus alternatives. It lacks context about prerequisites (like parent_id referring to a Phase 2 object), when to use this versus create_ipsec_phase2, or any exclusions. A one-line statement does not help the agent choose correctly among the many IPsec-related sibling tools.

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