v2_set_port_pvid

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

Adds genuinely useful behavior beyond the annotations: the tagged VLAN list is preserved unless replaced, trunks are refused without force:true, and read-only mode returns the payload instead of sending it. Annotations only declare idempotent/non-destructive; the description adds the trunk-refusal precondition and preservation semantics. Could go further on what happens to existing untagged membership.

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 definition and effect, then progressively adds edge cases (tagged preservation, trunk refusal, read-only mode). Efficient overall, though the parenthetical read-only banner is slightly jarring mid-definition.

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 mutation tool with no output schema and incomplete schema coverage, the description covers the important semantics: what changes, what's preserved, when it refuses, and the dry-run behavior. Missing coverage of the siteId/switchMac addressing params is the main gap.

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 low (29%), so the description must compensate, and it does for two key params: it defines pvidNetworkName as a VLAN name or tag ('MGMT' or '40' is in the schema too) and clarifies portName renames the port. It documents force's effect (allow trunks) in prose rather than repeating the boolean, and hints at dryRun via read-only mode. Still, port/siteId/switchMac are unexplained.

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) and resource (switch port's PVID) and explains what PVID actually means ('the VLAN an UNTAGGED frame lands on'), which makes the effect on untagged traffic unambiguous. This distinguishes it from more general siblings like v2_set_port or v2_set_ports_bulk.

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 usage context via the concrete scenario of a laptop plugged into a port and the rescue/console port case, plus an explicit restriction: refuses inter-switch trunks unless force:true. It lacks explicit 'when to use this vs v2_set_port_profile / v2_set_ports_bulk' routing, so it falls short of 5.

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