update_ipsec_phase2

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description accurately reflects a mutation operation ('Update') and adds no contradictory behavior. However, it provides no additional context beyond the annotations, such as whether updating an ID that doesn't exist will error, or whether partial updates are allowed. With annotations present, this is acceptable but not richly transparent.

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, compact sentence that front-loads the verb and resource. Every word adds clarity, with no redundant filler or restatement of the tool name.

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?

The tool has rich supporting structured data: a 13-parameter schema with 100% description coverage, annotations for idempotency and safety, and an output schema. Given this, the one-sentence description is adequate for an update operation. It could mention that the ID should come from search_ipsec_phase2s, but that is already in the schema's phase2_id description. Minor gap: no mention of the apply_immediately flag's effect, but that's in the schema.

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 the schema fully documents all 13 parameters. The description itself adds little parameter meaning beyond the required phase2_id. It confirms the update target is 'by ID', which aligns with the required parameter. Baseline 3 is appropriate given the schema does the heavy lifting.

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 a specific verb ('Update') and identifies the exact resource ('IPsec Phase 2 (Child SA / tunnel) entry') with a key qualifier ('by ID'). This clearly distinguishes it from sibling tools like create_ipsec_phase2, delete_ipsec_phase2, or search_ipsec_phase2s.

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 implies usage on existing entries via the word 'existing' and the ID requirement, but it does not explicitly state when to use this tool versus creating a new Phase 2 or deleting one. It also doesn't mention whether changes need to be applied separately (e.g., via apply_ipsec_changes), though the schema's apply_immediately parameter hints at this.

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