create_device_ipsec_phase1_interface

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

With no annotations, the description carries the load and does so well: it discloses that this is a write into the device DB, that the peertype default is a live-verified workaround for an FMG 7.6.7 'peer invalid value' rejection, that proposal/dhgrp are passed through largely unvalidated, and that echoed credentials are stripped from the result. It does not mention ADOM locking or that a commit/install is required for the change 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 opening sentence front-loads purpose and scope before the argument list, and the Args block is scannable with no filler entries. The peertype paragraph is longer than strictly needed and could be compressed, but the extra length buys real behavioral information rather than 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 16-parameter mutation tool with zero schema descriptions, the description supplies the enum values, defaults, conditional requirements and validation caveats an agent needs to construct a valid call. Return values need not be explained since an output schema exists. The missing piece is lifecycle context — ADOM lock/commit expectations after creating the object.

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 0%, yet the description documents essentially every one of the 16 parameters: enumerations for type, ike_version, mode, peertype, nattraversal, dpd; the 6-128 character constraint on psksecret; the conditional requirement that remote_gw be set when type is static; and the note that mode is ignored on IKEv2. This more than compensates for the empty schema descriptions.

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 specific verb and resource ('Create an IPsec phase1-interface (remote gateway / IKE SA) in a device's device DB') and explicitly disambiguates from the legacy policy-based 'phase1' table, which is exactly the confusion an agent would have. It also situates the object relative to the sibling phase2-interface tools.

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 scope constraint 'Route-based (interface-mode) tunnel only' tells the agent when this tool is the right choice versus the legacy policy-based path, and the 'interface' arg is defined as the outgoing local interface. There is no explicit pointer to follow-up calls (e.g. creating the phase2 child or committing the ADOM), so it stops just short of full when/how guidance.

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