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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuine context beyond them: API keys are masked, and read access to UniFi OS users is required. It does not discuss rate limits or pagination, but nothing material is hidden.

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?

Three short sentences, purpose front-loaded before caveats. The trailing 'Returns JSON: {...}' block restates what the output schema already defines, so it is mildly redundant, but it is compact and does no real harm.

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?

A zero-parameter, read-only tool with full annotation coverage and an output schema needs little prose. The description supplies purpose, use case, permission prerequisite, and a data-sensitivity note (masked keys) – everything an agent needs to call it correctly.

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 tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description correctly spends no effort on parameters.

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 precise scope verb+resource ('Who and what can access the console') and enumerates the three data domains returned (admin accounts, custom roles, API keys). No sibling tool covers access review, so the agent can distinguish it immediately from console/client/network siblings.

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 clear context for use ('useful for least-privilege reviews of integration accounts') and a prerequisite ('Needs read access to UniFi OS users'). It stops short of explicit when-not guidance or naming an alternative, but no sibling competes for this purpose, so the gap is minor.

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

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

Goes well beyond the annotations by disclosing that download builds a fresh archive into the server's download folder, is never returned to the caller, contains credentials, and requires elevated permissions. It also clarifies per-action safety (list read-only, create side-effecting), which the coarse tool-level annotations cannot express.

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?

Purpose is front-loaded in the first clause, then action-specific behavior and return shape follow in tight, information-dense prose. No sentence is wasted; each adds a distinct operational fact.

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?

Despite a rich output schema being present, the description helpfully summarizes both return shapes (list's data array vs download's saved_file with path/bytes/sha256) and covers the auth/environment prerequisites. Nothing an agent needs to call it safely 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?

With schema coverage reported at 0%, the description carries the burden and largely delivers: it explains action modes and the confirm requirement for create/download. It is less explicit about the 'target' parameter's per-part restriction (uos/network/users), leaving that to the schema, so it is strong but not fully compensating.

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 set (list/create/download) and resource (UniFi OS console backups), and immediately scopes it as 'whole console, not just the Network app'. An agent can distinguish it from sibling tools like unifi_console_network_list or unifi_console_support_file 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?

Explicitly explains each action mode and the prerequisites that gate them: create needs UNIFI_CONSOLE_ENABLE_WRITES=true and confirm=true, download needs confirm=true, and all console-level calls need Control Plane permission raised from View to Admin. It also marks list as read-only, giving clear when-to-use-and-what-it-requires guidance.

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

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

Adds substantial behavior beyond the annotations: secret redaction of x_* fields/passwords/keys, silent truncation of large results with guidance to narrow via fields/search/limit/offset, file downloads written to disk rather than returned, and the server-side write gate. This is consistent with readOnlyHint=false/destructiveHint=false and clarifies the actual safety envelope.

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?

Four short, front-loaded paragraphs ordered by importance: read/write policy, special cases, redaction/truncation, return shape. Every sentence carries operational information; no filler.

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 high-complexity generic dispatcher this is nearly complete: policy, gating flags, redaction, truncation, and response shape are all covered, and an output schema exists so return values need no further expansion. The missing piece is routing guidance against the overlapping specialized siblings.

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?

With reported schema coverage at 0% for the wrapper param, the description carries real weight: it explains confirm's exact trigger conditions, why fields/search/limit/offset exist (truncation mitigation), and that POST bodies only apply to query-style operations. It does not clarify path_params or query semantics beyond what the nested schema already states.

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+resource: 'Call one spec operation on the console', and the description makes the generic-dispatch role explicit by tying behavior to read vs write classes. It does not name the sibling workflow tools (unifi_console_list_operations / unifi_console_describe_operation) in the description itself, so differentiation is only partial.

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?

Strong when/when-not content: reads run immediately, configuration writes are refused, downloads and safe writes need confirm=true and sometimes UNIFI_CONSOLE_ENABLE_WRITES. However it never says when to prefer this generic call over the many specialized siblings (unifi_console_system_log, unifi_console_backup, unifi_console_support_file), which is a real decision the agent must make.

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

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

Annotations already flag destructive=true, idempotent=false and readOnly=false, but the description adds substantial context beyond them: the client is re-read to reject stale previews, fixed IPs are validated against real LAN subnets/gateway/broadcast/other clients/in-use addresses, Local DNS names are checked against other clients and static DNS records, writes are journalled, the result reports verified true/false plus a diff and an exact rollback call, and a fixed IP only takes effect at the next lease renewal. This is unusually rich behavioral disclosure for a mutation tool.

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 purpose and the two-step rule, then a dense but waste-free block of validation, auth, verification and rollback facts. Every sentence carries operational information, though the single long paragraph is heavier than it needs to be and could be split for scannability.

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, gated write tool with an output schema, the description covers everything an agent needs: the confirm/fingerprint handshake, the environment prerequisites, what is validated, what the response reports, and the rollback path. Return-value detail is correctly left to the output schema.

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% and the top-level 'params' wrapper is undocumented, so the description must carry meaning; it does explain the two parameters that matter most operationally, confirm and fingerprint, including that the fingerprint must come from the preview of exactly this change. Field-level detail for name/note/fixed_ip/local_dns_record lives in the nested schema descriptions rather than the tool description, so it does not fully compensate for the coverage gap, but it covers the non-obvious control flow.

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 pair (preview, then apply) and a specific resource (one known client) and enumerates the exact mutable fields (alias, note, fixed IP, Local DNS record). It is clearly distinguishable from siblings like unifi_console_static_dns, unifi_console_client_command and unifi_console_client_group, which touch related but different resources.

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: call with confirm=false for a preview, then call again with the same fields plus confirm=true and the fingerprint. It also states the preconditions (UNIFI_CONSOLE_ENABLE_WRITES=true and 'client' in UNIFI_CONSOLE_WRITE_ENTITIES) and the refusal condition for a stale preview, leaving nothing to inference.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds substantial context beyond them: exactly what forget destroys (history, name, note, fixed IP, Local DNS), which commands are reversible (block/unblock) and which are not (forget), that UniFi devices are refused, and that writes require UNIFI_CONSOLE_ENABLE_WRITES and 'client' in UNIFI_CONSOLE_WRITE_ENTITIES, plus journaling.

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-loads the two-step contract, then the per-command behavior, then the auth gate — a logical ordering with almost no filler. It is dense and somewhat long, but every clause carries operational meaning.

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 values need no explanation; the description covers the remaining burden — prerequisites, side effects, rollback, irreversibility, and the two-call protocol. An agent has everything needed to invoke this destructive tool safely.

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?

Reported coverage is 0% at the top level, so the description must compensate, and it does: it explains the confirm/fingerprint pairing, when discard_history is required and why, and the rollback implications of each command enum value. It largely restates the nested schema descriptions but adds the semantics (why the fields exist, what each command does) that a bare field description cannot carry.

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 set (block, unblock, reconnect, forget) on a specific resource (one client) and scopes it as preview-then-apply. It also implicitly distinguishes itself from sibling unifi_console_client by referring to 'the same switch as the client record tool.' An agent can pick it apart from siblings without opening the 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 procedure ('call with confirm=false ... call again with the same fields plus confirm=true and that fingerprint to apply') and states the conditions selecting each behavior. Rollback and irreversibility per command are spelled out, so there is nothing left to infer.

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

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

Annotations only declare destructive/non-idempotent; the description adds far more: stale previews are refused by re-reading the group, deletes are blocked while policies or traffic objects reference the group, edits take effect immediately for those consumers, the console requires the whole group so updates send all of it, and every write is journalled. MAC normalisation and post-write verification with a rollback call are also disclosed.

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 critical two-step confirm/fingerprint flow is front-loaded in the opening sentence and the remainder is earned by genuinely non-obvious constraints. It is dense at roughly ten sentences for one logical operation, and a couple of clauses (e.g. the 'type' replay rationale) could be trimmed without loss.

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?

Output schema exists so return values need not be restated, yet the description still usefully notes that the result carries verified true/false, the diff, and the exact rollback call. With prerequisites, deletion blockers, normalisation rules, and verification semantics all covered, an agent has everything needed to call this correctly.

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 reported as 0%, so the description carries the load; it explains confirm's two roles, that fingerprint must come from the preview of exactly this change, that members replaces the full list while add_members/remove_members are update-only deltas, and that MACs are normalised. It does not disambiguate target (id vs name) or the pass-through 'type' field, which the schema itself does cover.

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 pair ('preview, then apply, a change') and resource ('client groups'), and immediately glosses the resource as 'named sets of client MAC addresses used by policies', which separates it from the sibling unifi_console_client and unifi_console_traffic_object tools.

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 workflow (confirm=false preview, then confirm=true with fingerprint), states the prerequisite env vars for writes, and tells the agent when to use add_members/remove_members versus members. It stops short of routing against sibling tools (e.g. unifi_console_firewall_policy, which shares the 'used by policies' constraint), so it is clear context without explicit alternatives.

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

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

Goes well beyond the annotations: it discloses that shortening retention deletes older data at the next prune and longer retention consumes more storage, that writes are journalled, and that the fingerprint from the preview is required to apply. It also clarifies the read-only preview return fields and that untouched settings in the group are echoed back but never shown, which the destructiveHint annotation alone cannot convey.

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-loads purpose, then the two-step protocol, then fields, side effects and auth. Dense and mostly waste-free, though the field enumeration and the aside about auto-backup/analytics/Google Maps key could be tightened slightly.

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 values needn't be detailed, yet the description still names the preview payload (before, after, diff, warnings, fingerprint). Combined with the destructive-effect warning, auth requirements, and journalling note, nothing an agent needs to call this correctly 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?

Explains the semantics of confirm (preview vs apply), fingerprint (must come from the preview of exactly this change), and data_retention_setting_preference (auto vs manual gating the hours_* fields), which is meaningful even though the schema also describes them. It does not add much beyond the schema for the individual hours_* fields, so not a full 5.

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 pair (preview/apply) and a specific resource (how long the console keeps statistics and events), and pins the exact settings location (Control Plane > Network data retention). It is unambiguously distinguishable from all siblings, none of which touch retention.

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 the exact operating protocol: 'Two steps, always' – confirm=false for a read-only preview, then the same fields plus confirm=true and the fingerprint to apply. It also states the preconditions (UNIFI_CONSOLE_ENABLE_WRITES=true and 'data_retention' in UNIFI_CONSOLE_WRITE_ENTITIES), so an agent knows when the call will succeed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new context by confirming no console call is made and warning that spec descriptions carry quirks and secret-bearing fields. It stops short of describing failure behavior for an unknown operation_id.

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 short paragraphs, front-loaded with the action and immediately followed by the no-side-effect caveat. Enumerating the returned JSON keys is slightly redundant given an output schema exists, but the quirk warning earns its place.

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?

With an output schema present the description needn't restate return values, and annotations cover safety; what it must supply is the reason to call this before calling an operation, which it does. Only the input parameter's origin and error behavior are unaddressed.

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 description's field list ('name, in, required, description') refers to the returned parameters, not the input. It says nothing about the single input operation_id, whose meaning only comes from the schema's own description ('operationId from unifi_console_list_operations, e.g. listFirewallPoliciesWithHits'). With reported 0% schema coverage the description should have compensated for the input parameter and does not.

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: it shows one operation's parameters, request-body schema, access level and description from the spec. The line 'Does not call the console' cleanly separates it from the sibling unifi_console_call_operation, so an agent can pick the right tool without opening schemas.

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 clear when: inspect an operation before invoking it, because spec descriptions 'often record quirks such as Read-only despite POST'. It implies the pairing with unifi_console_call_operation but never names it or states an explicit when-not, so it falls short of a full 5.

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

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

Goes well beyond what the annotations declare: the mandatory preview/fingerprint/approval_note handshake, the pre-apply DNS probe that causes refusal, the one-shot auto-restore with applied=false and auto_restored=true, the env-var gate, per-write journalling and a recovery script. Nothing here is derivable from destructiveHint/idempotentHint, and the description is consistent with them.

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 two facts an agent most needs (preview-then-apply, tier C danger) before the operational detail, and almost every sentence carries non-redundant information. It is dense and slightly long, with some restatement of fields the schema already describes.

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 tier-C mutation with an output schema, the description covers the workflow, the failure and rollback paths, the authorization prerequisites, and the manually-applied follow-on (restore script). An agent has everything needed to call it correctly without reading the schema.

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 every field (state enum meanings, confirm, fingerprint, approval_note, server_names, custom_servers), so the field enumeration is largely redundant. The added value is the conditional applicability the schema lacks: server_names applies to manual, custom_servers to custom, and 'the list that does not apply is cleared, as the UI does'. action/target are left unexplained in prose.

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?

Opens with a specific verb and resource: preview then apply a change to the gateway's DNS over HTTPS (DoH) setting. The scope is unambiguous and clearly separable from siblings such as static_dns and dynamic_dns, and the first sentence also flags the blast radius ('it can stop DNS for the whole network').

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 explicit sequencing ('Two steps, always: call with confirm=false ... call again with the same fields plus confirm=true') plus prerequisites (UNIFI_CONSOLE_ENABLE_WRITES, 'doh' in UNIFI_CONSOLE_WRITE_ENTITIES) and a scope exclusion ('SSL inspection is a separate setting and is not changed here'). It never names a sibling tool to route to, so it lands at 4 rather than 5.

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

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

The annotations already flag this as non-readonly and destructive, but the description adds far more: the token is write-only, never read back (listed under secret_fields_not_verified), not journalled; deleting discards the token permanently and rollback can only recreate with a fresh one; every write is journalled. That is rich behavioral context beyond the structured flags.

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?

It is front-loaded with the two-step pattern and well ordered (preview/apply, then update, then token, then delete), and every sentence carries load for a destructive secret-handling tool. It is dense and runs long, but the length is mostly justified by the complexity.

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, multi-step, secret-bearing operation it covers workflow, prerequisites, parameter interplay, and side effects, and an output schema exists so return-value detail is not needed. An agent has everything required to call it correctly.

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?

Beyond the per-field schema text, the description supplies cross-field semantics the schema cannot express: an update keeps the id and must resend the whole entry plus token_env even when only other fields change; delete requires discard_token=true with confirm=true; fingerprint must come from the preview of exactly this change. These interdependencies materially help correct invocation.

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 opening sentence names a concrete verb set (creation, update, deletion) and a specific resource (a Dynamic DNS entry on the gateway), and the tool name separates it from the static-DNS sibling. An agent knows exactly what domain this operates in without opening the 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?

It states the mandatory two-step workflow, exactly when to pass confirm=false versus confirm=true plus fingerprint, and the environment prerequisites (UNIFI_CONSOLE_ENABLE_WRITES=true, 'dynamic_dns' in UNIFI_CONSOLE_WRITE_ENTITIES). Nothing about when/how to invoke 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.

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: the mandatory preview/apply handshake, the DNS test wrapped around changes with automatic single rollback, the exposure/outage refusals requiring acknowledge flags, and the env-var prerequisites (UNIFI_CONSOLE_ENABLE_WRITES, UNIFI_CONSOLE_WRITE_ENTITIES). It even states every write is journalled. No contradiction with 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?

Dense and front-loaded: the risk tier and the preview-then-apply rule come first, followed by actions, then safety guards. Every sentence carries operational weight for a Tier C destructive tool, though the paragraph is long enough that an agent must parse several clauses to extract the call sequence.

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 values (before/after/diff/fingerprint) need not be re-explained, and the description still summarises what the preview returns. Prerequisites, refusal conditions, rollback behaviour and the two-call protocol are all present, leaving nothing essential for a correct invocation 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?

Schema description coverage is reported as 0%, so the description must carry meaning, and it explains the highest-risk parameters well: the action set (create/update/enable/disable/delete/move), confirm's two-step semantics, fingerprint, approval_note, position/relative_to for move, enabled-on-create, and the acknowledge flags. It leaves secondary fields (logging, report_flow, ip_version, policy_action, connection_state, allow_return, and the Endpoint sub-fields) unexplained, so it compensates substantially but not fully.

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?

Opens with a specific verb pair and resource: 'Preview, then apply, a change to one custom zone-based firewall policy.' It also scopes the target ('one custom zone-based firewall policy') which cleanly separates it from siblings like unifi_console_firewall_policy_hits or unifi_console_port_forward. An agent can identify the operation without opening the 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?

Explicit two-step workflow: call with confirm=false for a read-only preview, then call again with confirm=true plus fingerprint and approval_note. It names the exclusions (system-defined policies and generated '(Return)' copies are never changed) and the conditions under which writes are refused. This is unusually complete routing guidance.

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

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

Annotations already establish readOnlyHint/idempotentHint/destructiveHint=false, yet the description still adds real value: the Integration API does not expose hit counts (explaining why this tool exists), the read-only guarantee, and the shape of the returned record. It stops short of pagination, rate-limit, or refresh/latency behavior, so it is strong but not exhaustive.

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, then audit use cases, then the read-only caveat, then the return contract. Three tight blocks with no filler or repetition of the title.

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?

Purpose, selection criteria, safety posture, and the sibling to use for writes are all present; parameter detail lives in the nested schema and an output schema exists, so restating return fields is optional. An agent has everything needed to select and call this correctly.

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 description contributes nothing about the input parameters — its only field list is the response payload, not the request. The nested schema descriptions (e.g. "'hits' ascending surfaces unused rules first") do the work, but with the reported 0% description coverage the prose was expected to compensate and does not.

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?

Specific verb and resource ('List zone-based firewall policies') plus the distinguishing payload ('hit counts and last-hit time, for audits'). This separates it cleanly from the sibling unifi_console_firewall_policy, which handles policy mutation, without the agent needing to open either 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 concrete when-to-use conditions ('audits', 'unused rules (zero hits), noisy rules and stale rules') and an explicit when-not with a redirect: 'to change policies use the existing firewall tools'. Only weakness is that the alternative is referred to generically rather than by exact tool name, but the routing intent is unambiguous.

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

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

Annotations already cover readOnlyHint/idempotentHint/destructiveHint, so the safety profile is known. The description adds meaningful non-obvious behavior: it searches a static spec rather than the live console, and it filters to currently-callable operations by default. It does not describe rate limits or how the corpus is refreshed, so not a full 5.

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, then workflow, then the negative constraint — efficient and well ordered. The inline JSON return block is somewhat redundant given an output schema exists, which is the only minor waste.

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 spec-search tool with rich annotations and an output schema, the description supplies everything an agent needs: what it searches, the workflow position, the fact it doesn't hit the live console, and default filtering. Nothing material 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 coverage is only the single 'params' wrapper, but the nested ListOperationsInput schema fully documents tag, limit, access, offset and search. The description adds no param-level syntax beyond the statement that only callable operations are shown by default (aligning with access='read'), so it does not compensate for the reported coverage gap. Baseline 3.

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+resource (search the UniFi OpenAPI spec for operations) and scopes it precisely to undocumented controller/UniFi OS APIs plus the Integration API. It is clearly distinguishable from siblings like unifi_console_describe_operation and unifi_console_call_operation, which it names.

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 three-step workflow ('Use this first to find an operationId, then unifi_console_describe_operation, then unifi_console_call_operation') and an explicit exclusion ('Does not call the console'). An agent knows exactly when to reach for this tool versus the other two.

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

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.

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds substantial context beyond them: preview contents, fingerprint binding, post-change verification ('every connected device must still be connected and DNS must still work'), automatic single rollback on failure, new networks created disabled, and journaling of every write. This is unusually rich behavioral disclosure.

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-loads purpose and the tier-C warning, then moves to the required two-step flow and finally to constraints and exclusions. It is dense and longer than average, but nearly every clause carries operational weight; a small amount of tightening is possible.

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, multi-action network tool this covers everything an agent needs: the mandatory preview/apply cycle, the approval and acknowledgement gates, auth/env requirements, failure and rollback behavior, and unsupported feature areas. An output schema exists and the description appropriately describes the preview contents rather than restating return shapes.

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 reported at 0%, so the description must carry weight, and it does for the workflow-critical fields: confirm/fingerprint/approval_note semantics, the two acknowledge_* flags with their triggering conditions, and enabled's create-only behavior. It does not explain the DHCP-related fields (dhcp_start/stop/dns/lease), though the schema itself describes those, leaving a small 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?

Opens with a concrete verb+resource+scope: 'Preview, then apply, a change to a LAN/VLAN network,' and immediately flags the risk class ('Tier C: a wrong change can cut DHCP, the VLAN and routing for a whole segment'). This clearly separates it from the read-side sibling unifi_console_network_list and from other write tools.

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 (confirm=false preview first, then confirm=true with the same fields, fingerprint and approval_note), plus the conditions that gate the write: acknowledge_infrastructure for console/switch/AP/gateway networks, acknowledge_disconnect for disruptive edits with clients attached, and env-var prerequisites. It also states exclusions ('WAN, VPN, IPv6 and DHCP options are not offered'), which is exactly the when-not guidance an agent needs.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safe-vs-write profile is covered, yet the description adds far more: stale previews are refused because the list is re-read first, applying requires UNIFI_CONSOLE_ENABLE_WRITES=true and 'network_list' in UNIFI_CONSOLE_WRITE_ENTITIES, edits take effect on dependent policies immediately, deletion is blocked while in use, results are read back and verified, and every write is journalled with an exact rollback call.

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 workflow is front-loaded in the opening sentence and the remaining prose is dense but non-redundant, with each clause carrying a distinct operational fact. It is on the longer side for a description, but nothing reads as filler.

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?

Given the mutation risk, the two-step safety protocol, the environment prerequisites, the dependency blocking rules, and an output schema (so return values need not be described), the description covers everything an agent needs to invoke this tool correctly and safely. No significant gap remains.

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?

Every nested field carries a schema description, so the schema does most of the per-parameter work and the baseline is 3. The description goes beyond it by explaining the confirm/fingerprint contract as a workflow-coupled pair and by clarifying the fingerprint must come from the preview of exactly this change, which is the semantics an agent most needs.

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 names a specific verb and resource: it manages (preview then apply) changes to a console's network lists, and immediately defines what those are (port, address and domain lists used by firewall policies). This lets an agent distinguish it from sibling tools like unifi_console_firewall_policy and unifi_console_traffic_object without opening any 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?

The usage model is stated explicitly and operationally: call with confirm=false for a read-only preview, then call again with the same fields plus confirm=true and the returned fingerprint to apply. When-to-use is unambiguous, and exclusions are supplied (a list still referenced by firewall policies or traffic objects cannot be deleted).

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: what power supervisors do and how to read consecutive_failures as an active power-cycle signal. That is genuine diagnostic semantics beyond the structured fields.

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 resource, then the diagnostic guidance, then the return shape — each sentence earns its place except the JSON shape line, which restates what the output schema already provides.

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?

Strong on diagnostic intent and interpretation, and the return payload is already documented by the output schema. The only gap is that the required device_mac argument is never addressed in the description, relying entirely on the schema.

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 description never mentions the single device_mac parameter, so it adds no meaning over the schema. The schema property itself does carry format guidance and a hint to find the MAC via device-list tools, so an agent is not left stranded, but the tool text contributes nothing here.

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?

Names a specific verb+resource and scope: 'PoE budget for one switch plus the site's power supervisors'. The parenthetical definition of power supervisors as watchdogs that power-cycle ports makes the resource unambiguous and clearly distinct from sibling switch_port_detail.

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 usage trigger ('Check this before diagnosing a PoE device that keeps rebooting') and even the interpretation rule (consecutive_failures above zero = power-cycling). No alternative sibling is named and no when-not condition is stated, so it stops short of a 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description goes well beyond them: the rule is re-read before apply, a new rule is created disabled, enabling exposes a host to the internet, the result reports verified true/false with a diff, an exact rollback call is returned, and every write is journalled. That is exactly the mutation-risk context an agent needs.

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 purpose leads, then a single dense paragraph of prerequisites, workflow, and safety consequences. Every sentence carries information, but the block is long enough that a little structural separation (e.g. the env-var requirement on its own line) would improve scanability.

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 write tool this covers the full lifecycle: preview, fingerprint guard, required env flags, verification read-back, and rollback. An output schema exists, so return shape need not be restated, and nothing an agent needs to call it correctly 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?

Reported top-level schema coverage is 0% (the single 'params' object carries no description), but the description compensates by explaining the confirm/fingerprint coupling, the create-only nature of enabled, and the safety meaning of enabling a rule. It adds real semantics, though it does not enumerate the field-level parameters the nested schema already documents.

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 pair (preview then apply) and a precise resource: the console's port forwards, glossed as internet-to-LAN rules. That resource is unambiguous against every sibling (firewall_policy, wan, static_dns), so an agent can route correctly, though the description never explicitly contrasts itself with a neighbouring tool.

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?

It prescribes the exact call sequence (confirm=false first, then confirm=true with the fingerprint), states prerequisites (UNIFI_CONSOLE_ENABLE_WRITES=true and 'port_forward' in UNIFI_CONSOLE_WRITE_ENTITIES), and explains what happens when preconditions fail (stale preview refused). This is explicit when/when-not guidance, not inference.

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

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

Annotations only give coarse hints (destructive, non-idempotent, non-readonly). The description adds substantial context: the rule is re-read so a stale preview is refused, a new rule starts switched off unless enabled=true, the console requires the whole rule so updates resend everything, verification returns verified true/false plus a rollback call, and every write is journalled. This is exactly the kind of behavior an agent cannot infer from 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-loads the two-step workflow and the sibling disambiguation before the field-level detail, and essentially every sentence carries operational weight. It is dense and long, but the density is justified by the tool's complexity; a slight trim of the enumeration would not lose meaning.

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?

With an output schema present, return values need not be restated, and the description nonetheless clarifies that the result reports verified status, diff, and rollback call. Combined with the write prerequisites, staleness handling, and delete behavior, an agent has everything needed to invoke this correctly.

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 reported at 0%, so the description must carry the load, and it does: it explains wan_network (WAN or VPN link), source_clients (MAC addresses), destination_apps (application ids), units for download_limit/upload_limit (kbit/s, 10000 = 10 Mbit/s), burst semantics (OFF/SHORT/LONG), and objective behavior (LIMIT caps, PRIORITIZE has no limits). It also flags which raw fields are replay-only.

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, a change to the console's QoS rules') and immediately disambiguates from the nearest sibling by naming unifi_console_traffic_object for Traffic Management objects. An agent can tell this apart from the other unifi_console_* tools without opening any 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?

Spells out the mandatory two-step flow (confirm=false preview, then confirm=true with the same fingerprint) and when to use each action (create, update, enable/disable, delete). It also names the prerequisite toggles (UNIFI_CONSOLE_ENABLE_WRITES, 'qos_rule' in UNIFI_CONSOLE_WRITE_ENTITIES) so the agent knows the conditions under which a write will even be accepted.

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

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

Annotations already declare the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower; the description still adds real context: it logs in if needed, reports cookie lifetime, CSRF rotation, and server safety settings. The 'Logs in if needed' side effect sits in mild tension with readOnlyHint=true (session establishment writes state), but it is idempotent and non-destructive to the controller configuration, so this is disclosed rather than contradictory.

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?

Three tight sentences, front-loaded with purpose, then the when-to-use trigger, then the return shape. The explicit 'Returns JSON' line is slightly redundant given an output schema exists, but it is brief and not wasteful.

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 zero-parameter diagnostic with rich annotations and an output schema, the description covers everything an agent needs: what it inspects, that it may log in, when to reach for it, and the shape of the result. Nothing material 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level detail is needed or missing.

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 concrete verb and resource — checks the connection and reports the running account, its permissions, session facts, controller version, and server safety settings. This diagnostic/status role is clearly distinguishable from the 28 sibling tools, which are resource-specific operations (firewall_policy, wifi, poe_overview, etc.).

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 says 'Use it first when a call fails with a permission or authentication error,' giving a clear triggering condition. It stops short of naming an alternative or a when-not-to-use case, but no sibling serves as a substitute for this diagnostic, so the guidance is effectively complete.

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

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

Annotations declare the safety profile (destructive, non-idempotent, not read-only), but the description adds substantial context beyond them: the mandatory preview/apply handshake, fingerprint staleness enforcement, the write-enable env vars (UNIFI_CONSOLE_ENABLE_WRITES, static_dns), read-back verification with a verified flag, a rollback call, and journaling. It also explains that the console only accepts the whole record, which is essential for a mutation tool.

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 core two-step workflow, then layers on validation, prerequisites, and post-apply behavior. It is a dense block rather than short, but nearly every sentence conveys actionable information; only the warnings enumeration is slightly list-like.

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 mutation tool with an output schema, the description supplies everything an agent needs: the two-phase call sequence, prerequisites, validation behavior, and post-apply verification/rollback. Return-value details are correctly left to the output schema.

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 reported at 0% for the wrapper object, so the description carries weight here, and it does add meaning: confirm/fingerprint semantics, the full-record update rule, and the impact of applying (re-read, verified, rollback). It does not restate per-field rules (target, ttl, record_type), which the nested schema does document, so it stops at 4 rather than fully compensating.

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+resource: managing the gateway's Local DNS records, and enumerates the record types (A, AAAA, CNAME, MX, SRV, TXT) it covers. The 'Local DNS' scoping cleanly separates it from the sibling unifi_console_dynamic_dns, so an agent can pick the right tool without opening either 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 explicit procedural guidance: call with confirm=false for a preview, then call again with the same fields plus confirm=true and the fingerprint, with the note that stale previews are refused. It also lists the refusal/validation conditions (duplicates, CNAME rule, names a client already publishes). It never names an alternative tool or says when NOT to use this one, so it stops short of a 5.

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

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

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=false) by disclosing that the bundle contains plain-text secrets, is saved locally and never returned, takes ~a minute, and requires UNIFI_CONSOLE_ENABLE_WRITES=true, confirm=true, and Control Plane=Admin. These are exactly the auth/side-effect facts an agent needs before calling a write tool.

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 scope, followed by tightly grouped prerequisites, side effects, and return shape. Every sentence earns its place, though the secret-handling, permission, and timing details make it denser than strictly necessary for a 6-parameter tool.

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?

Even though an output schema exists, the description summarizes the return shape for both scopes and covers permissions, timing, secret risk, and scope behavior. Nothing an agent needs to invoke this destructive-adjacent write safely 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?

The description clarifies the meaning of scope ('device' starts generation and reports status only vs console download) and the rationale for confirm=true, adding real semantics. The nested schema itself documents targets, recreate, device_mac and wait_seconds, so the low coverage signal is an artifact of the top-level 'params' wrapper; the only minor gap is that wait_seconds isn't connected to the '~a minute' guidance.

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?

Specific verb+resource ('Generate a support file and ... download it to disk') with clear scope differentiation between console and device. An agent knows exactly what this produces and where it lands, and the behavior is distinct from every sibling (system_log, backup, etc.).

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 concrete when-to-use context: 'the place to look when regular logs do not explain a fault (e.g. an STP problem visible only in device syslog)', which implicitly routes away from unifi_console_system_log. However, it never names an alternative tool or an explicit when-not-to-use, so it stops short of a 5.

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

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

Adds substantial context beyond annotations: the preview/apply flow, fingerprint binding, refusal of risky fields on uplink/infrastructure ports unless acknowledge_infrastructure=true, automatic single rollback if connected devices are lost, journalling, and the whole-port-list save requirement. This is fully consistent with destructiveHint=true and does not contradict idempotentHint=true.

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-loads the core purpose and the two-step requirement, then layers risk and exclusions in dense, purposeful sentences. Despite the length, every sentence adds operational guidance for a high-risk mutation tool.

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?

Given the output schema exists, the description need not explain return values. Annotations already declare the safety profile, and the description supplies workflow, guardrails, prerequisites, rollback behavior, and exclusions. Complete for an agent to invoke the tool correctly at a high level.

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 the top-level params object, so the description must compensate. It gives meaning to confirm, fingerprint, approval_note, acknowledge_infrastructure, and groups risky fields, but does not explain many nested parameters such as poe_mode, lldpmed, reset, or keepalive. Partial compensation only.

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, resource and scope: preview then apply a change to ONE port of ONE switch, and flags Tier C risk. An agent can distinguish it from unifi_console_switch_port_detail, which reads a port rather than changing it.

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 describes the two-step workflow (confirm=false preview, then confirm=true with fingerprint and approval_note) and lists prerequisites (UNIFI_CONSOLE_ENABLE_WRITES, 'switch_port' in UNIFI_CONSOLE_WRITE_ENTITIES). It also states what is not offered: disabling a port, STP edge mode, port profiles, and other switch settings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely useful context by disclosing the record-trimming behavior (1 MB+ record reduced, kept-key rules so new firmware fields surface) and that secrets are removed. This is real behavioral disclosure beyond structured fields.

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?

Three tight sentences, front-loaded with the core purpose and the return shape last. The key-matching parenthetical is dense but directly explains behavior, so 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?

With an output schema present it need not explain return values, and annotations cover safety; the description still adds the trimming rule. The remaining gap is routing guidance against the many sibling switch/port tools and the required device_mac workflow.

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?

It mentions the optional LLDP toggle, mapping to include_lldp, and describes field filtering. But it says nothing about the required device_mac or the ports subset filter, so with low schema coverage the description only partially compensates for the two undocumented parameters.

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+resource and scope: live per-port state for a switch, enumerating exactly what is reported (link, STP state/role, flaps, errors, PoE, LLDP). An agent can distinguish this from a generic switch/device listing, though it does not explicitly name the closest sibling (unifi_console_switch_port).

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?

No explicit when-to-use guidance, no exclusions, and no mention of the sibling tools it could be confused with (unifi_console_switch_port, unifi_console_poe_overview). Usage is only implied by the word 'live', and the 'find it with existing device list tools' hint lives in the schema, not the description.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true) by disclosing the preview/apply handshake, the fingerprint requirement, that changing or stopping the destination ends the feed to the current receiver, that the host/port are mirrored to ip/port, and that the group is read back, verified and journalled. This is exactly the extra context annotations cannot carry.

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-loads the workflow before the field list, and most sentences carry real information (warnings, auth, verification). The flat comma-separated field inventory is the weakest part and slightly pads the paragraph, but nothing is seriously 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 write with a preview gate, the description covers the workflow, the safety warnings, the auth prerequisites, the verification and journalling, and an output schema exists so return values need not be explained. An agent has everything needed to invoke it correctly.

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 top-level schema ($ref to params) exposes no description, but the enumerated field list in the description largely restates what the nested SyslogInput schema already documents. The one genuine addition beyond the schema is the note that host and port are also written to ip and port; otherwise this is a name inventory rather than added meaning.

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+resource with scope: 'change to the console's remote syslog setting (where logs are sent and which categories)'. An agent can tell this apart from siblings like unifi_console_system_log (reading logs) and unifi_console_logging_levels without opening either 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 clear operative guidance ('Two steps, always: call with confirm=false ... then confirm=true with that fingerprint') plus the preconditions to apply (UNIFI_CONSOLE_ENABLE_WRITES=true, 'syslog' in UNIFI_CONSOLE_WRITE_ENTITIES). However, it never names an alternative tool or a when-not-to-use condition, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: what categories of events are recorded, the default time/severity window, and that critical_only bypasses the time window and paging. It does not mention rate limits or pagination limits beyond what the schema implies.

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 purpose, then behavior, defaults, the critical_only escape hatch, and the return shape. Every sentence contributes, though the return-format block is somewhat redundant given an output schema exists.

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 multi-parameter, read-only query tool with annotations and an output schema, the description covers purpose, defaults, severity semantics, and the critical_only special case. It omits guidance on category filtering and on choosing between this and sibling log tools, but nothing critical to invoking it correctly 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?

The description reinforces key parameter semantics: critical_only switches to the Critical view with no time window or paging, and min_severity defaults to MEDIUM with LOW described as Wi-Fi connect/roam noise. The nested schema properties themselves carry full descriptions, so the schema does most of the work; the description adds useful nuance on top rather than filling a 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?

States a specific verb and resource ('Query the UniFi System Log'), anchors it to a UI location (the Network app's 'System Log' page), and enumerates the event families it covers (STP loops, PoE/port faults, WAN failovers). It distinguishes itself from 'the older event list' but never names a sibling tool, so an agent still has to infer how it differs from unifi_console_syslog or unifi_console_logging_levels.

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 concrete operating context: defaults to last 24 hours at MEDIUM+, and explicitly routes to critical_only=true for switching faults with example event names. It stops short of naming when NOT to use this tool or which sibling log tool to prefer, so it is clear context without exclusions.

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

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

Adds substantial behaviour beyond the annotations: the mandatory two-step preview/apply with fingerprint, stale-preview refusal via re-read, whole-object send semantics, post-apply read-back with 'verified true/false' plus diff and rollback call, journalling, and the gating env vars UNIFI_CONSOLE_ENABLE_WRITES / UNIFI_CONSOLE_WRITE_ENTITIES. This materially exceeds what destructiveHint/idempotentHint alone convey.

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-loads purpose, then the mandatory workflow, then field semantics, then constraints — a sensible order for a high-complexity tool. The single dense paragraph is longer than ideal and could be broken into clearer clauses, but almost every sentence carries operational information rather than filler.

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, multi-field mutation tool this covers the full arc: preview/confirm handshake, prerequisite acknowledgements, what is left untouched, required env configuration, whole-object update semantics, verification, rollback, and journalling. With an output schema present, the description is not obliged to detail return values yet still flags the key fields reported back.

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?

With reported coverage at 0% on the top-level params object, the description compensates substantially, explaining friendly fields, units ('download_limit / upload_limit in kbit/s (10000 = 10 Mbit/s; 0 switches one off)'), burst modes, schedules, and the route_*/acknowledge_* pairing. Some of this duplicates the nested schema descriptions, but for a single opaque 'params' argument the added semantics are genuinely useful.

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?

Opens with a specific verb+resource+scope: 'Preview, then apply, a change to the console's traffic objects (Traffic Management: bandwidth limits and priority, schedules, internet blocking and routing for networks or clients).' It enumerates create/change/delete via the action field and names the sub-domains it governs, letting an agent separate it from siblings like unifi_console_qos_rule or unifi_console_firewall_policy.

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 explicit operational guidance: 'call with confirm=false to get a read-only preview ... call again with the same fields plus confirm=true and that fingerprint', and states blocking/rerouting 'need acknowledge_blocking / acknowledge_reroute when the object is switched on'. It also states what it does not edit (app, domain, region matchers, local-network block). It stops short of naming sibling tools as alternatives, so 4 rather than 5.

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

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.

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

Annotations already flag destructive/non-idempotent, but the description adds substantial context beyond them: no automatic restore, new SSIDs created disabled, passphrase is write-only via passphrase_env and never previewed/journalled, every change is journalled, and writes require UNIFI_CONSOLE_ENABLE_WRITES plus entity allow-listing.

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-loads the one-line purpose, then the 'Two steps, always' rule, then constraints. Dense but each sentence carries operational information; some clauses could be tightened but nothing is filler.

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, multi-step write tool with an output schema present, the description covers the workflow, fingerprint chaining, prerequisites, and irreversibility. Return-format details are unnecessary given the output schema, so nothing critical 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?

With reported 0% schema coverage, the description carries the burden and does so for the key semantic parameters: confirm, fingerprint, approval_note, passphrase_env, acknowledge_open and acknowledge_disconnect are all explained in prose. It is not exhaustive (e.g. bands, pmf_mode, l2_isolation are not explained), so a 4 rather than 5.

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, a change to a Wi-Fi network (SSID)') and the annotation title enumerates create/change/delete. It is clearly distinguishable from siblings like unifi_console_network or unifi_console_wan, which operate on other resources.

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 explicit when-to-use guidance for the two-step flow (confirm=false for preview, then confirm=true with fingerprint and approval_note) and names the conditions that gate the write (acknowledge_disconnect, acknowledge_open). It does not name or route away to any sibling tool, so it stops short of full alternatives coverage.

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