unifi_console_firewall_policy

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.