esxi_network_manage

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, so the agent knows this is a disruptive write operation. The description adds meaningful behavioral context: use resource_schema/get and default preview first, specify expected_host for precision, enable write switches, confirm dependencies, and use request_id to prevent duplicate execution. These are operational behaviors beyond the annotations. However, it doesn't explain what gets destroyed or the consequences of the write switches, and the description is more of a workflow instruction than a disclosure of side effects. A 3 is appropriate.

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 a single dense paragraph listing many actions and then workflow instructions. It is front-loaded with the action list, which is useful, but the long enumeration is somewhat unwieldy and the workflow sentence is packed. It is reasonably concise but could be better structured (e.g., separated into purpose, prerequisites, and execution notes).

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 has 9 parameters, a nested 'arguments' object, and complex multi-action behavior, the description is only partially complete. It covers the general workflow and some parameters but leaves many details (action validation, argument structure, individual switch semantics) unaddressed. An output schema exists, so return values need not be explained. Missing parameter semantics and edge cases keep this at 3.

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%, so the description must compensate, but it only names a few parameters implicitly ('expected_host', '写开关' for allow_disruption/allow_unknown_impact/allow_protected_impact, 'request_id', 'dry_run' via 默认预览). It does not explain the 'action' enum values, the 'arguments' object structure, or the meanings of the allow_* switches. With 9 parameters and zero schema descriptions, this is a significant gap, but the description does mention some key parameters and their workflow role, meriting a 3 rather than lower.

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 names a clear resource ('network 管理') and enumerates the specific operations covered (switch_create, portgroup_create, vmkernel_create, dns_update, route_update, etc.). This is a broad multi-action tool, and the action list gives good purpose clarity. It distinguishes itself from siblings like esxi_list_networks (read) and esxi_firewall_manage by covering the specific network mutation actions.

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 provides explicit workflow guidance: '先 resource_schema/get 和默认预览' (first use resource_schema/get and default preview), plus '实际执行精确 expected_host、写开关与依赖确认' (for actual execution, specify expected_host, write switches, and dependency confirmation). This tells the agent the prerequisite steps and when to set specific parameters. It lacks explicit when-not-to-use guidance or alternatives, so 4 rather than 5.

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