pvsyst_create_tracking_variant

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 thoroughly: preview creates nothing, execution creates exactly one new VC, the source is preserved, lock/path/snapshot/readback behavior is reused, and native_consumption_verified remains false until a separate native run is reviewed. It also discloses that no tracking, backtracking, irradiance, or shading model is computed and explains inherited versus explicitly set fields.

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 description is a dense wall of domain-specific constraints with many clauses packed into long sentences. Most content is useful, but readability and conciseness suffer; it would benefit from tighter grouping or bullets.

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 mutation tool with no annotations and no output schema, the description covers prerequisites, side effects, preview behavior, inheritance rules, units, domains, verification caveats, and readback behavior. It is nearly complete, though it does not describe error behavior or a concrete return/response shape beyond mentioning readback and a public getter.

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 substantial meaning: control units are meters, degrees, and m/s; booleans are strict; min/max pairs preserve source values on the unchanged side; AxisAzim/MinPhi/MaxPhi retain adapter domains; and other numerics have 0.1 adapter precision. It does not individually document every nested TrackingControls field or fully specify variant_name/add_utf8_bom behavior beyond referencing existing display-name rules.

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 first sentence states a specific verb and resource: preview or create a NEW variant editing only the source native tracking record. It clearly distinguishes this specialized tracking-variant operation from broader variant tools such as pvsyst_update_variant_parameters and pvsyst_clone_variant.

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 preconditions: the source must already have a supported native tracking FieldType, exact recorded field shape, one counted orientation1, one PV-only Grid subarray, and complete circuit counts. It also says controls must belong to that FieldType and unspecified values remain inherited. It does not explicitly name alternative tools to use when those conditions fail, which keeps it below a 5.

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