unifi_console_logging_levels

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

Annotations only declare readOnly=false, idempotent=true, destructive=false; the description goes well beyond that with the fingerprint handshake, the fact that current levels are not reported and results cannot be read back (verified is null), debug's storage impact, and the env-var prerequisites (UNIFI_CONSOLE_ENABLE_WRITES, UNIFI_CONSOLE_WRITE_ENTITIES). Journalling of writes is also disclosed. This is rich behavioral context, not a restatement of the annotations.

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 the action and the mandatory two-step pattern, and every sentence carries operational information. Slightly dense, with the parenthetical enumeration of preview contents and the service list duplicating schema content, but nothing is padding.

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 write tool with an output schema, this covers everything an agent needs: the preview/apply handshake, prerequisites, the irreversibility caveat, and the risk of leaving debug on. The mention that 'verified is null' usefully pre-empts a false expectation about the response.

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?

The nested schema already documents each field (defaults of warn, 'Only update exists', fingerprint provenance), so the schema does much of the work. The description still adds combination-level semantics the schema cannot express: 'With no fields, or setting_preference=auto, everything returns to the console's defaults (warn)' and the fingerprint's role across the two calls.

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 ('Preview, then apply, the logging level ... of the Network application's services: device, mgmt, sdn, system') and names the two allowed values. No sibling tool touches logging levels, so the resource is unambiguously distinct.

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?

Explicitly prescribes the two-step workflow (confirm=false for preview, then confirm=true with fingerprint), states when to use debug ('for diagnosis') and the obligation to revert it ('put it back'). The when/when-not guidance is fully spelled out.

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