v2_set_port

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

Annotations only state readOnly=false, idempotent=true, destructive=false; the description adds genuinely non-derivable behavior: the trunk-port refusal, the force override, and the read-only mode that returns the payload instead of applying it. The blast-radius warning about partitioning the network is exactly the kind of operational context an agent cannot infer from 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 capabilities, then safety warning, then behavioral caveats—logical ordering with no filler. The feature enumeration is dense but earns its space; the only minor cost is a long single sentence before the warning.

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 17-parameter mutation tool with no output schema and sparse schema descriptions, the definition covers purpose, safety constraints, and the dry-run/force escape hatches well. Residual gaps: no mention of what a successful response contains and no sibling routing for bulk operations.

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 only 18% across 17 params, so the description has to compensate, and it does by grouping the params into meaningful feature clusters (loopback detection, STP on/off, edge-port, BPDU/root guard, storm-control thresholds, isolation, PoE, disable). It also explains force and dryRun semantics, though it doesn't add units or validation detail for the storm thresholds—those rely on the schema.

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 specific verb and resource ('Set one switch port') and enumerates the exact feature set the tool controls (loopback detection, STP/edge port/BPDU guard, storm control, isolation, PoE, enable/disable). The 'one' scope also implicitly separates it from the bulk sibling v2_set_ports_bulk and from v2_set_port_pvid / v2_set_port_profile.

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 gives a strong when-not-to guidance ('NEVER enable loopback detection on a switch-to-switch trunk') and a precondition for sensitive cases ('refuses trunk ports unless force:true'). What's missing is explicit routing to alternatives such as v2_set_ports_bulk for multi-port changes, so usage context is clear but not comparative.

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