pvsyst_validate_variant_structure

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 well: it discloses that dome/unknown list quantities are 'unchecked', explains the tri-state `valid` semantics (false/null/true), describes version-specific MPPT comparison behavior, and returns subarray_ids/power_sharing_id for shared parents. It does not state permissions or read-only nature explicitly, but the validation nature is evident and the result-side behavior is unusually well disclosed.

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?

Every sentence carries real behavioral content, but the text is a wall of internal jargon (TOrientGroup, $0400, MPPT nodes) with no front-loaded summary and no paragraph separation, making it hard to parse quickly for tool selection. It is information-dense rather than wasteful, but poorly structured for an agent scanning options.

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?

With no output schema and no annotations, the description compensates well by explaining the `valid` field semantics, the 'unchecked' reporting behavior, and returned fields for shared parents. Given the tool's complexity, an agent has enough to understand what a call returns, though the unexplained parameters leave a residual gap.

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?

Both parameters (`project`, `variant`) have 0% schema description coverage, and beyond the parenthetical "(Projects & Variants)" header the description never explains what these references are or how to obtain them. The description thus does not compensate for the schema gap.

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 specifically what it checks: orientation IDs/references, grid circuit references, serialized inverter/string counts, and shared parent allocation. It also explicitly excludes other kinds of validation ("not voltage/current or physical validation"), which helps differentiate it from validate_component. It loses a point only because there is no single front-loaded verb+resource sentence stating 'validate variant structure', so the reader must assemble the purpose from a list of internal checks.

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?

There is no explicit when-to-use/when-not guidance or routing to alternatives (e.g., validate_component or get_variant_components). The requirements it lists (owned MPPT/string children, matching Version=8.1.0/8.1.6, common group 0/all -1) are preconditions for a passing result rather than guidance on when to invoke the tool.

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