iaas_update_fabric_vsphere_datastore

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds the genuinely valuable scope note that only tags are mutated, but it does not address permissions, whether unlisted existing tags are replaced or merged, or what the PATCH returns.

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 core constraint is front-loaded, but the first sentence is duplicated verbatim ("Update Fabric vSphere Datastore." twice), wasting space in an otherwise four-line description. The endpoint path is useful context, not waste.

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?

This is a mutation tool with a nested body object and no output schema, so the description carries extra burden. It covers the mutation scope but leaves the important open question — whether the other body properties are ignored or rejected — unresolved, which is exactly what an agent needs before calling it.

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 100%, so all three parameters are documented in structured data. However "Only tag updates are supported" is meaningful beyond the schema because the body schema exposes allocatedNonDiskStorageSpaceBytes and maximumAllowedStorageAllocationPercent as if they were writable, and the description implicitly contradicts that — a clarification that is left ambiguous rather than spelled out.

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 Fabric vSphere Datastore") and adds the scope-limiting constraint "Only tag updates are supported." It does not, however, distinguish this tool from close siblings such as iaas_get_fabric_vsphere_datastore, iaas_update_fabric_network, or iaas_update_fabric_compute, so an agent must infer the boundary.

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?

"Only tag updates are supported" implies the intended use case (tagging) and implicitly excludes other update scenarios, which is useful. But there is no explicit when-to-use/when-not guidance, no pointer to the read sibling for inspecting a datastore first, and no note on whether the other body fields will be ignored.

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