router_add_port_forwarding

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

With no annotations, the description carries the full burden, and it does disclose two meaningful behaviors: a confirm flag is required to actually add the rule, and force bypasses a 'Network Guard' safety check. However, it never explains what Network Guard is, whether the rule takes effect immediately, or whether it conflicts with existing rules — significant gaps for a mutation tool with zero annotation coverage.

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 sentence is front-loaded and the parameter block is a tight one-line-per-parameter list with no filler. Slightly verbose in docstring style, but every line carries information the schema does not.

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 not be explained, and the parameter documentation is thorough. What is missing for a write operation on a router is the surrounding context: persistence across reboot, interaction with existing rules, and the meaning of the Network Guard bypass.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description fully compensates: all seven parameters are documented with meaning and concrete examples, plus semantics the schema lacks — internal_port defaults to external_port, protocol is constrained to TCP/UDP/ALL, and force bypasses Network Guard. The only small gap is that confirm is described circularly ('confirmation flag to add rule').

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource: creates a new NAT virtual server port forwarding rule on the router. The verb distinguishes it from the get_/del_ siblings, but the description never names those siblings or clarifies the boundary with router_set_dmz / router_set_upnp, which are also ways to expose internal services.

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?

There is no explicit when-to-use guidance, no mention of prerequisites such as admin auth, and no routing to alternatives like DMZ or UPnP for the same goal. The only usage-adjacent content is the confirm and force flags, which are invocation mechanics rather than guidance on when this tool is the right choice.

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