delete_port_forward

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

No annotations are provided, so the description carries the full burden. It clearly states the deletion action and its target, which is transparent as far as it goes. However, it does not disclose consequences like irreversibility, effect on active traffic, or permission requirements. This is adequate for a simple delete tool but leaves some behavioral nuance unstated.

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 description is brief and well-structured: the action is front-loaded, and parameter details follow in a compact format. Every sentence adds value and there is no redundant or vague wording.

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 simple delete operation with three parameters, the description covers all parameter semantics and the source for the ID. An output schema exists, so return values need not be explained. It lacks explicit warnings about permanence or side effects, but that is a minor gap given the straightforward nature of the tool.

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%, but the description compensates well by defining all three parameters: host (name, ID, or composite MAC:numericId format), site (name or ID), and forward_id (required, obtained from list_port_forwards). This gives the agent everything needed to fill the parameters correctly.

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 opens with a clear verb and resource: 'Delete a port forwarding rule by ID.' It also references the sibling tool list_port_forwards for obtaining the ID, which helps distinguish it from create/update port forwarding 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?

It explicitly instructs the agent to obtain forward_id from list_port_forwards, indicating when it is appropriate to call this tool. It does not explicitly mention create/update alternatives, but the delete operation is self-evident and the source of the required ID is clearly stated.

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