list_ipsec_proposals

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured domain behavior: that lifetime must be compared against both phase 1 and the far end's proposal, with cloud-provider lifetimes as a third value. It does not, however, mention pagination, result size, or how the name_filter narrows results.

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?

Two compact sentences, with the core purpose front-loaded and the comparison caveat relegated to a note. The note is slightly digressive about the far end and cloud providers but each clause carries actionable information for interpreting the output.

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?

An output schema exists, so return-value documentation is rightly omitted, and annotations cover the read-only semantics. The remaining hole is input understanding: with two undocumented parameters and no guidance on how device/name_filter behave, an agent can call the tool but cannot confidently target the right device or filter.

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 0% for both parameters, so the description carries the full burden and provides nothing about 'device' or 'name_filter' — not even whether device selects among multiple routers. The parenthetical (encryption, auth, PFS, lifetime) describes the returned resource, not the inputs, so it does not compensate for the gap.

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 states a specific verb and resource ('Lists the IPsec proposals') and scopes it to phase 2 with the fields it contains. It implicitly distinguishes itself from the sibling list_ipsec_profiles by framing that tool's data as 'phase 1 lifetime' on /ip ipsec profile, though the contrast is left for the reader to assemble.

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?

There is no explicit when-to-use or when-not-to-use statement, and no named alternative beyond the passing reference to /ip ipsec profile. The lifetime-comparison note does imply a diagnostic use case (mismatched SA lifetimes causing tunnel instability), which is usable but requires inference.

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