vpc_detach_from_instance

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

Annotations are empty, so the description carries all responsibility for behavioral disclosure. It states that a VPC is detached and that a success confirmation is returned, but does not discuss mutability, even whether detaching is reversible, whether the VPC must already be attached, or what side effects may occur. The description is not fully transparent given the lack of annotations.

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 compact, logically organized with sections for the main action, identifier resolution, arguments, and return value. There is no wasted text, and the description fits on a single screen while staying clearly readable.

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 there is an output schema, the return value is adequately covered. However, the description lacks context on behavior such as whether the VPC must currently be attached, what happens if it is not, and how the detachment affects instance connectivity. It's adequate minimal, but leaves gaps for a mutating action.

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 schema description coverage at 0%, the description fully compensates by describing all three parameters, their expected value types and defaults (e.g., vpc_identifier accepts VPC/VPC 2.0 description or ID; instance_identifier accepts label, hostname, or ID; vpc_type has defaults). The 'Smart identifier resolution' example also provides real guidance. Some detail about ambiguity is missing, but it is largely adequate.

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 clearly states the action: 'Detach VPC or VPC 2.0 from an instance.' It uses a specific verb and resource, and is easily distinguished from sibling tools like vpc_attach_to_instance. No ambiguity about what the tool does.

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 little guidance on when to use this tool versus alternatives. It mentions smart identifier resolution, but does not explain when this detach tool is appropriate, nor does it mention any prerequisites, exclusions, or use cases where another sibling tool would be preferred.

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