pvsyst_clone_variant

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: embedded site/meteo and external references are preserved rather than synchronized, inspect_project reports differences, and optional edits target specific subsystems. It still omits collision behavior, permissions, and what happens if new_variant already exists.

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 purpose is front-loaded and every sentence adds some constraint or behavior. The prose is dense with jargon like 'VC' and 'PRJ', but it remains compact for a six-parameter tool with no schema descriptions.

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?

There are no annotations and no output schema, so the description must provide complete context. It covers preservation and edit-target semantics well, but it does not explain return behavior, collision handling, or required preconditions for creating a new variant.

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 must compensate. It adds useful meaning for source_project defaulting and subarray_id strict integer typing, and clarifies that updates keys like PAN/OND/BTR/GEN target particular subsystems, but it leaves project, source_variant, and new_variant largely defined only by their names.

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: 'Copy a variant as a NEW VC in project.' It distinguishes this from project-level cloning by emphasizing variant copying and cross-project import, so an agent can separate it from pvsyst_clone_project and pvsyst_clone_subarray.

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?

It explains the source_project default and the cross-workspace import case ('supply another workspace PRJ'), which implies usage context. However, it never names alternatives such as pvsyst_clone_project or pvsyst_create_* variant tools, so the agent must infer when this tool is preferred.

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