router_set_wifi_radio

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

With no annotations at all, the description carries the full burden and does substantial work: it discloses the self-disconnect hazard, the confirm gate, and that force bypasses a Network Guard safety check. It omits persistence behavior (does the radio/SSID change survive reboot?) and any auth/permission requirements.

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 destructive warning is front-loaded immediately after the one-line purpose, then parameters are listed compactly. Every line does work — nothing duplicates structured data because the schema documents none of these parameters.

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 mutating radio tool with five undocumented-in-schema parameters, the description covers purpose, hazard, and all parameter meanings, and an output schema exists so return values need not be explained. The remaining gap is post-change behavior (reboot requirement, effect on connected clients) which an agent would want before calling.

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% and the schema has no enums, but the Args block supplies the exact band literals ('2.4GHz' or '5GHz'), the semantics of enable, the optionality of ssid, the purpose of confirm, and what force actually bypasses. This adds genuine meaning the schema cannot convey.

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 pair plus resource and scope ("Enables or disables a Wi-Fi radio (2.4GHz or 5GHz) and optionally updates its SSID"). It is clearly distinguishable from read-side siblings like router_get_wifi_networks and from router_set_guest_wifi, though neither sibling is named explicitly.

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 a concrete precondition (confirm=True is mandatory) and an explicit hazard condition (disabling the band you are connected to drops the host). It stops short of naming alternatives such as router_set_guest_wifi or stating when to prefer them, so it is strong but not complete.

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