configurar_trunk

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so well. It discloses the critical platform nuance: on 3560/3650 multilayer switches 'switchport mode trunk' is rejected unless 'switchport trunk encapsulation dot1q' is set first, while that command does not exist on 2960 switches. It also reveals that the function queries the real model in PT and sends the appropriate command set, which is rich, non-obvious behavior.

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 front-loaded with the purpose, followed by parameter guidance, then the critical platform warning, then the example. Every sentence earns its place, including the BEWARE note and the example call. It is slightly long but the length is justified by the genuinely important switch-model caveat.

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?

Given the tool's real complexity (it must adapt commands based on switch model), the description covers the essential ground: purpose, parameter semantics, and the behavioral caveat that differentiates switch models. The presence of an output schema relieves the description of explaining return values. Nothing an agent needs to invoke it correctly is 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?

With 0% schema description coverage, the description must compensate. It fully explains vlans_permitidas ('all' vs comma-separated list) and provides a concrete call example demonstrating switch and puerto usage. The two required parameters are self-evident from their names, but their accepted format (e.g., how to reference a port) is only illustrated, not specified.

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 states a specific verb and resource: 'Configures a port as 802.1Q trunk' with the use case (switch-to-switch link or switch↔router for router-on-a-stick). This clearly distinguishes the tool from siblings such as configurar_vlan and asignar_puerto_vlan, which handle access-port VLAN assignment rather than trunk configuration.

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?

The description gives clear context for when the tool applies (trunk links, router-on-a-stick) and the example shows the intended call. However, it never explicitly says when NOT to use it or names the alternative tools (asignar_puerto_vlan for access ports, configurar_vlan for VLAN creation), leaving the routing decision to inference rather than explicit exclusion.

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