update_wlan

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

Annotations only carry destructiveHint=true, and the description enriches this substantially: 'Mutating operation: applied immediately and persisted on the UniFi console', the partial-update guarantee ('only the fields you provide change'), and the passphrase/pmf_mode behavioral notes. No contradiction with the destructiveHint annotation exists.

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 paragraph is tightly worded and front-loaded, with every sentence earning its place. However, the Args section copies the full 11-parameter schema verbatim, which is redundant noise for an agent that already receives the input schema, making the description longer than needed.

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 an 11-parameter destructive mutation with no output schema, the description covers the essential ground: target resolution, partial-update semantics, persistence, allowed pmf_mode values, and an inspection path. It omits failure modes and preconditions (e.g., what happens to connected clients), but an agent can call this tool correctly with what is provided.

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 baseline is 3. The description's Args block is a near-verbatim duplicate of the schema. It adds global framing (partial updates) and a subtle passphrase hint, but individual parameter meaning is not enriched beyond what the schema already provides.

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 opens with a specific verb and resource: 'Update a wireless network (SSID)'. It immediately disambiguates from siblings like create_wlan and delete_wlan, and clarifies partial-update semantics. The phrase 'Inspect with get_wlans' further separates it from its read-mode counterpart.

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 gives clear operational context: how the target is resolved ('resolved by ID or name'), that the operation is applied immediately, and that get_wlans is the companion inspection tool. However, it never explicitly states when NOT to use this tool in favor of create_wlan or delete_wlan, so the exclusion guidance is left to inference.

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