vcluster_create

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds valuable context beyond the schema: the caller's kube context is never switched, later values files override earlier ones, create_namespace follows CLI defaults, and kubeconfig_path falls back to environment defaults. It could also mention prerequisites like requiring the vcluster CLI or cluster access, but the disclosed behavior is substantial.

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 well-structured with a short purpose statement, followed by an Args section and a Returns section. It is long only because all 12 parameters need explanation. There is slight redundancy between 'Create a new vcluster' and 'Creates a vcluster with the specified name,' and the Returns section is less necessary given the output schema, but overall each section earns its place.

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 complex 12-parameter tool, the description covers every parameter, key defaults, precedence rules, a significant side-effect guarantee (no kube-context switching), and the return type. It provides enough information for an agent to call the tool correctly without needing to open the schema, which is remarkable given the parameter count.

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 0%, so the description is the only source of parameter meaning. It documents all 12 parameters, including defaults, override behavior, example inline values, and the effect of flags like expose and create_namespace. This far exceeds the bare schema titles and fully compensates for the lack of schema descriptions.

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 opens with a specific action and resource: 'Create a new vcluster' and restates 'Creates a vcluster with the specified name.' This clearly distinguishes it from sibling tools like vcluster_list, vcluster_describe, vcluster_delete, and vcluster_pause, which cover other lifecycle operations.

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 gives strong parameter-level guidance, such as 'Later files override earlier ones' and set_values 'Avoids writing a temporary values file for a single setting.' However, it does not explicitly contrast this tool with siblings or state when to prefer vcluster_create over related lifecycle tools, leaving most comparison to inference from the tool name.

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