iaas_change_security_groups

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

Annotations already declare non-readonly, non-idempotent, non-destructive, open-world, so the description is not carrying the whole safety burden. It does add real value by disclosing the same-deployment scoping constraint on which security groups can be added or removed. It says nothing about permissions, whether the call is asynchronous/request-tracked, or whether the supplied list replaces or merges existing assignments, which matters for a mutation with idempotentHint=false.

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 opening sentence is restated almost verbatim by the second sentence, and the phrase 'Securing group that is part of the same deployment' is garbled. There is no waste of length, but restating the same point twice plus a typo costs it clarity value.

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 a nested body and no output schema, the description covers the operation and its main precondition, but leaves out the replace-vs-merge semantics and any indication of what the call returns or whether it is async. With 100% schema coverage the parameter surface is well documented, so the remaining gap is behavioral rather than structural.

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 100%, so the baseline is 3. The description reinforces that the target is a machine network interface and that groups are added/removed, mapping loosely to networkInterfaceSpecifications.securityGroupIds. It does not clarify the most consequential ambiguity: whether securityGroupIds is a full replacement set or an additive/delta change.

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 and resource: changing security groups on vSphere machine network interfaces. The second sentence clarifies that groups can be added or removed per network interface. However, it never distinguishes this from siblings such as iaas_reconfigure_security_group, iaas_update_security_group, or iaas_patch_machine_network_interface, all of which sound plausibly relevant to the same task.

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?

There is one constraint (the security group must be part of the same deployment) but no statement of when to pick this tool over the many sibling security-group and network-interface tools. An agent facing a 'change SG' request has no disambiguation guidance and must infer from the name and path alone.

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