unifi_console_wan

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds substantial context the annotations cannot convey: the ~20 second gateway re-provision, the post-change validation checks (connectivity, WAN ok, internet probe, DNS), automatic single-attempt rollback, the required UNIFI_CONSOLE_ENABLE_WRITES=true and 'wan' in UNIFI_CONSOLE_WRITE_ENTITIES environment gates, and that every write is journalled. This is exactly the auth/impact disclosure the lower bar rewards.

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?

Front-loaded with purpose and the 'Tier C' risk, then the workflow, then preconditions and post-change behavior. Dense but each sentence carries operative detail (fingerprint, approval_note, env flags, rollback). Slightly long, but almost nothing is wasted.

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 destructive, non-idempotent mutation, the description covers the safety workflow, required approval, identity acknowledgement, environment gates, timing, validation and rollback. With both annotations and an output schema present, nothing an agent needs before invoking (or before deciding not to) 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?

Top-level schema coverage is reported at 0%, so the description must carry the load. It explains the semantics of the workflow-critical parameters (confirm, fingerprint, approval_note, acknowledge_identity) and groups the 'Identity' fields (MAC override, WAN VLAN, connection type, IPv6 type, uplink identity) that require acknowledgement. It does not enumerate the ~30 leaf fields, but the nested schema titles and enum constraints cover those, so this is a strong assist.

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 ('change to the WAN network settings') and immediately scopes it ('Only update exists. A WAN is never created, deleted or disabled here'). This lets an agent separate it from siblings like unifi_console_network or unifi_console_firewall_policy without opening a schema.

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 an explicit two-step protocol: first confirm=false to get the preview, then a second call with the same fields plus confirm=true, the fingerprint and an approval_note. It also names the precondition for identity changes (acknowledge_identity=true) and states plainly what is not offered (the uplink password and unlisted fields).

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