pvsyst_create_shed_geometry_variant

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

With no annotations, the description carries the full burden and delivers real behavioral context: preview creates nothing, saving never sets native_consumption_verified to true, unrequested data/hardware/topology are preserved, native alone computes shading and electrical grouping, and failures disclose partial artifacts without automatic cleanup. Gaps remain on permissions/auth requirements and on what a successful call returns, which matters since there is no output schema.

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 in the first clause, and almost every clause carries information, so there is little filler. But the delivery is a dense semicolon chain of run-on technical fragments that is hard to scan and forces repeated re-parsing to extract the validation rules.

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, guarded mutation tool with no annotations and no output schema, the description covers creation semantics, validation domains, inheritance/preservation rules, snapshot and no-overwrite guards, and partial-failure behavior. Missing pieces are the authorization preconditions and the shape of a successful response (it only hints that a getter exposes stored fields for create/read/create closure).

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 largely does: it gives domains for angles (0..90 tilt, -180..180 azimuth), lengths/factor scaling, positivity rules for pitch/collector/cell width, inactive-band nonnegativity and sum-below-collector-width, 0..1 factor, and strict positive 32-bit counts and booleans. It also touches the top-level params ('Preview', 'Optional name/BOM rules'), but it does not map units field-by-field and the phrase 'Angles use 0.1 degrees' is ambiguous as to whether it means unit scale or precision.

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?

States a specific verb and resource up front: 'Preview or exclusively create a NEW native Sheds/SunShields variant,' which separates it from the tracking, dome-allocation, and clone siblings by resource type. It adds scope detail (one orientation/subarray, complete grid counts, no type conversion) but never names an alternative sibling, leaving the disambiguation implicit.

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?

Preconditions are stated densely ('Use an existing recorded type with one orientation/subarray and complete grid counts... no load/storage/P50/horizon or active geometry/layout'), which implies when the tool is applicable. However, there is no explicit routing guidance such as when to prefer pvsyst_create_tracking_variant, pvsyst_clone_variant, or pvsyst_update_variant_components, and no stated when-not-to-use condition beyond the constraint list.

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