pvsyst_create_grid_storage_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 real behavior: dry-run writes nothing, execution creates a new variant while retaining source PRJ/VC, battery filename/counts and topology, and allow_grid_export maps only to native bit27. It also explicitly negates likely misreadings ('not a charge-from-grid switch,' 'does not construct hybrid ports'). It omits permission requirements and failure modes, and the dense prose makes the disclosure hard to extract.

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 first sentence is well front-loaded and most sentences carry distinct constraints, but the whole is a ~300-word run-on with redundant negative statements ('not a charge-from-grid switch and not a hybrid DC-port setting. This does not construct hybrid ports...') and no visual structure, which slows an agent trying to extract call requirements.

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?

Given no annotations, no output schema, 0% schema coverage and nested objects, the description is unusually complete: validation semantics, strategy constraints, retention behavior, and the getter/null rule are all covered. It still does not describe what this tool's own response contains on preview versus creation, which matters for a 7-parameter mutation tool.

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: SOC fractions bounded 0..1 with min<max, PMaxCharge/PMaxDisch defined as AC-side limits rather than hybrid DC ratings, efficiencies as percent with Euro<=max, and full availability-profile semantics (ISO interval-start hours, fixed standard offset, at least one outage). The mapping from prose terms like 'PMaxCharge' to the actual parameter names (max_charge_ac_kw) is left implicit, and some parameters (e.g., dry_run, new_variant) get only indirect treatment.

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 opening sentence states a specific verb and resource: 'Preview or create a NEW VC from an existing native AC-coupled Grid storage template,' which separates it from pvsyst_create_grid_storage_system and pvsyst_clone_variant by scope. It never names those siblings explicitly, so the differentiation is implied rather than stated.

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 conveys that 'Preview writes nothing' while execution creates a new VC, and it enumerates preconditions for the WeakGrid strategy and for supported 8.1.0/8.1.6 declarations. It does not state when an agent should choose this over create_grid_storage_system or clone_variant, leaving usage to inference.

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