iaas_update_external_network_ip_range

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

Annotations already disclose that this is a non-read-only, open-world, non-idempotent, non-destructive mutation. The description adds useful context about assigning the range to a different network and/or changing tags, but it does not explain side effects, permission requirements, or what happens to existing associations. It also mentions tag changes that the schema does not expose.

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 short and front-loaded: it states the update operation first, then specifies the intended effects, then gives the underlying PATCH endpoint. There is little wasted text, though the unsupported tag claim reduces reliability.

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 should make the observable change clear. The annotations cover the safety profile, but the description omits permissions and side effects, and it incorrectly suggests tag changes are supported when the body only accepts fabricNetworkIds.

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 schema already documents id, body, fabricNetworkIds, and apiVersion. The description does not name or clarify those parameters, and its reference to changing tags is misleading because the body schema contains no tags field. This earns below the high-coverage baseline of 3.

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: update an external IPAM network IP range. It also distinguishes the operation from read-only and delete siblings by saying it assigns the range to another network and/or changes tags. However, the mention of changing tags is not supported by the input schema, which slightly muddies the stated scope.

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 implies this is the tool for updating an external network IP range, but it gives no explicit when-to-use guidance. It does not compare it with alternatives such as iaas_update_internal_network_ip_range, nor does it mention prerequisites or exclusions.

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