pvsyst_clone_subarray

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

With no annotations, the description carries the full behavioral burden and does so extensively: it states that a rollback snapshot is saved, the variant hash is required, shared power and external references are unsupported, and specific MPPT layouts are preserved or rejected. It also discloses return fields such as orientation_id, orientation_cloned, and shared_parent_created. This is unusually rich behavioral disclosure for a mutation tool.

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, but the body is a dense wall of technical clauses with no bullets, headings, or paragraph breaks. Most sentences contain necessary constraints, but the lack of structure makes the definition harder to scan than it needs to be. It is adequately sized for a complex operation but not concise in presentation.

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, unannotated mutation tool with six parameters and no output schema, the description covers prerequisites, supported and unsupported cases, snapshot behavior, and return fields. It gives the agent enough information to avoid common invalid invocations, including MPPT layout restrictions and version-specific requirements. The remaining omission of project and variant semantics is minor because those are standard context parameters.

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, and it adds meaningful semantics for source_subarray_id, expected_sha256, clone_orientation, and share_inverter. It warns that source_subarray_id must be a strict JSON integer and ties expected_sha256 to the current variant hash. It does not explain project or variant, though those are likely obvious from context, leaving a minor gap rather than a major one.

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 verb and resource: duplicate a grid subarray and its exclusively owned inverter groups. This clearly distinguishes the operation from broader sibling tools such as pvsyst_clone_variant and pvsyst_update_variant_components. The functional scope is immediately understandable despite the dense detail that follows.

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 substantial conditional guidance for the clone_orientation and share_inverter modes, including preconditions and the explicit warning not to combine them. It does not, however, compare this tool to sibling alternatives or state when to choose cloning versus creating or updating subarrays through other tools. Usage context is clear but lacks explicit alternative routing.

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