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 richly: dry_run downloads and writes nothing, execution writes raw provider response plus CSV plus provenance manifest, existing files are not overwritten, null hours are never filled or interpolated, and unsafe timezone-offset cases are blocked. It also discloses the temperature method as a linear approximation and the dependence on provider publication status.

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 description is dense but front-loaded: the core action and subject come first, followed by input-mode rules, year constraints, execution behavior, and exclusions. Every sentence carries operational meaning for an 11-parameter tool and nothing is merely repeated from structured fields.

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 the absence of annotations, an output schema, and schema parameter descriptions, the description is largely complete on safety, file outputs, and input constraints. It still omits the meaning of altitude and csv_name and does not state what the tool returns directly for dry-run versus execution beyond describing written files.

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 across 11 parameters. It explains the location_id versus latitude/longitude alternatives and the required companion fields for explicit coordinates, plus year, dry_run and temperature_method semantics, but it leaves altitude and csv_name unexplained.

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 starts with a specific verb and resource: planning or executing one Open-Meteo ERA5 year as a PVsyst standard hourly weather CSV. It scopes the tool to Sites & Weather and explicitly points to pvsyst_resolve_location for location_id, making it distinguishable from nearby weather tools.

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 clearly defines the two valid input modes, forbids mixing them, gives the valid year range and publication requirement, and states that dry_run is the default. However, it does not explicitly compare itself with other weather-building siblings such as pvsyst_prepare_weather or pvsyst_build_monthly_weather.

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

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

With no annotations present, the description carries the full burden and does well: it discloses that the operation is reversible, that an archive directory is the destination, that confirmation is gated, and that referencing projects cause rejection. It omits what error surface the reference check returns and whether the archive is workspace-scoped or global.

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?

Two tight sentences with zero filler; the bracketed category prefix and the safety requirement are front-loaded so the agent reads the constraint before the action.

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?

No annotations and no output schema, yet the description covers reversibility, destination, gating, and failure conditions, which is enough to invoke correctly. The missing component_type vocabulary is the only real gap for a 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. It clarifies 'confirm' as a required safety gate and constrains 'filename' to unreferenced components, but 'component_type' has no enum and no explanation of accepted values, leaving one of three parameters semantically thin.

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: reversibly remove an unreferenced workspace component to a .mcp-archive location. The component scope is clear, which implicitly separates it from pvsyst_archive_project and pvsyst_restore_archived_component, though it never names those siblings.

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?

Gives concrete preconditions: the component must be unreferenced by workspace PRJ/VC files, and confirm=true is required. The alternative restore path is not referenced, so an agent must infer which tool undoes this, but the when-to-use conditions are otherwise explicit.

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

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 key safety behavior: hash matching before archiving and mandatory confirmation. It does not explain reversibility, permission requirements, mismatch handling, or what archive actually does to the project state.

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 definition is a single dense sentence with no filler. Category, operation, limit, precondition, and confirmation requirement are all front-loaded and easy to scan.

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 destructive project-level operation with no annotations, no output schema, and a nested parameter object, the description covers the core precondition and safety gate. It still leaves gaps around expected_files structure, failure behavior, and post-archive state.

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. It explains that 'expected_files' participates in hash matching and that 'confirm=true' is required, which adds real meaning, but it does not document the nested map format, project identifier expectations, or edge cases.

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 gives a specific verb and scope: archive up to 128 PRJ/VC members. The '[Projects & Variants]' label and member limit help distinguish it from the sibling pvsyst_archive_variant, though it does not explicitly name that alternative.

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 gives an implied precondition ('after matching every hash') and notes 'confirm=true', which helps an agent understand required setup. However, it does not say when to choose this over pvsyst_archive_variant or pvsyst_restore_project_archive, nor does it describe exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the safety constraints: do not archive the last variant, use a SHA guard, and require confirm=true. However, it omits what archiving does to the variant, whether it is reversible, permission requirements, and response behavior.

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 description is a single front-loaded sentence with no filler. It is appropriately brief, though the abbreviation 'VC' and compressed phrasing reduce immediate clarity.

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 mutation tool with no annotations, no output schema, four parameters, and 0% schema coverage, the description is too sparse. It covers the key preconditions but leaves parameter meanings, permissions, reversibility, and return behavior unexplained.

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 explain the four parameters. It only hints at confirm and expected_sha256 via 'SHA guard' and 'confirm=true', leaving project and variant undocumented and not clarifying the SHA parameter's exact role.

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 (archive) and resource (VC/variant), plus a clear precondition that another variant must remain. The abbreviation 'VC' is slightly less clear than 'variant', but the tool name and condition make the purpose unambiguous.

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?

Gives an implied usage condition: archive only when at least one other variant remains, and with confirm=true. It does not explicitly compare against pvsyst_archive_project or pvsyst_restore_variant, nor does it state when not to use this tool beyond the remaining-variant constraint.

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

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

With no annotations, the description carries the full burden. It usefully discloses the destination directory and that the copy is byte-identical, but says nothing about overwrite behavior for an existing backup, failure modes, permissions, or what is returned on success.

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?

A single front-loaded sentence with the '[Components]' grouping tag and the destination path, with no filler. It is terse but nothing is wasted; the gaps are completeness gaps rather than verbosity.

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 write tool with zero annotations, no output schema, and two fully undocumented parameters, this is under-specified. The agent cannot tell what values to supply for component_type or how the backup relates to the existing archive/restore family.

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% for both parameters. 'filename' is ambiguous — is it the source file to back up or the destination name? — and 'component_type' gives no hint of its allowed values or how it constrains the lookup. The description adds no parameter meaning to compensate.

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 ('save a byte-identical backup') plus the destination path, which is more precise than a bare 'backup'. It is distinguishable from archive/restore siblings by the 'byte-identical' qualifier, though it never explicitly contrasts with pvsyst_archive_component.

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?

No statement of when to use this versus archive_component, copy_component, or restore_archived_component, and no prerequisites such as the component needing to exist. The agent is left to infer the trigger condition from the name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only discloses that a file is written at a specific path. It is silent on overwrite behavior, what happens to an existing CSV, whether the directory is created, and units (Wh/m² vs kWh/m², °C). For a write tool with zero annotation coverage this is a substantial gap.

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?

A single front-loaded sentence with no filler, and the artifact definition leads. The '[Sites & Weather]' category prefix is family boilerplate rather than tool-specific information, which is the only mild waste.

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 5 undocumented parameters, no annotations, and no output schema, the description should at minimum pin down array length enforcement, units, and optional-field behavior. None of that is present, leaving an agent unable to construct a call correctly without guesswork.

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% across 5 parameters, so the description must compensate and largely does not. It does add one useful semantic hint — '14-row' implies each array argument must supply 14 monthly values — but it never maps parameter names to meaning, states units, or explains the behavior when diffuse_h / wind_velocity are omitted (null defaults).

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 concrete verb (create) and a concrete artifact (14-row monthly weather CSV) plus its destination path (workspace/Meteo), so the agent knows exactly what is produced. It also implicitly distinguishes itself from the acquire/convert/inspect weather siblings by being the one that authors the monthly CSV consumed by create-site. It stops short of explicitly naming those siblings.

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 phrase 'for create-site' implies the downstream consumer, giving an implied usage context, but there is no explicit when-to-use/when-not guidance and no alternatives are named (e.g. pvsyst_convert_meteo, pvsyst_prepare_weather, pvsyst_inspect_weather_csv). The agent must infer this is the manual authoring path when no source weather file exists.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the export returns native PVsyst values rather than a separate storage calculation and that some columns may legitimately be omitted depending on native run configuration. It does not state whether an existing definition is overwritten, what permissions or workspace conditions are required, or what the tool returns on success.

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 sentence, and the variable-specific details are relevant. However, the prose is dense, semicolon-heavy, and structured more like reference notes than a clean tool description; it also spends space on variable details while omitting the required filename parameter.

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?

There is no output schema and no annotations, so the description should be fairly complete. It covers variable semantics well enough to choose an export mode, and it explains native-value caveats, but it leaves the required filename and the creation/overwrite behavior undocumented. Adequate but with clear gaps.

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. It gives substantial meaning for the 'variables' choices (grid_storage, soiling, grid_limit, shading) and their caveats, but it never explains the required 'filename' parameter, nor does it mention the default 'all_common'. Partial compensation only.

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 a specific verb and resource: 'Create a NEW hourly export definition in workspace/Models.' That is clear enough for an agent to know what the tool produces. However, it does not distinguish this tool from nearby siblings such as pvsyst_read_results, pvsyst_read_rows, or export/delivery tools, and the '[Simulation]' tag is ambiguous.

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 explains which variables to select for particular review scenarios, but it never says when to use this tool rather than alternatives such as pvsyst_read_results, pvsyst_read_rows, or pvsyst_export_engineering_delivery. The conditional guidance is parameter-level detail, not tool-selection guidance.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that dry_run performs no writes and returns provenance/inherited params/diff, that creation writes a new component plus a Results source record, that existing paths are never overwritten, that a failed creation rolls back the source record so retries are safe, and that outputs remain needs_review rather than certified. It even scopes what is not certified (datasheet authenticity, layout, model applicability).

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 and safety-critical behavior are front-loaded, and every sentence addresses either scope, parameter semantics, or write safety. It is dense but not padded; minor redundancy like repeating 'never overwrites existing paths' twice keeps it from a 5.

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 10-parameter, nested-object, unannotated mutation tool with no output schema, the description covers behavior well but leaves significant parameter-level gaps: the structure of sources/declarations, what template_name expects, and the meaning of source_library enums are not described anywhere. An agent could not construct nested payloads from this description alone.

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 does partially: it explains PAN vs OND field sets with units (PNom W, ISC/Imp A, Voc/Vmp V; PNomConv kW, VMppMin/Max/V, EfficMax/Euro %), dimension/weight units, and the acknowledge_inherited_model requirement. But 10 parameters including nested sources/declarations objects and enums (source_library, component_type) are not fully addressed — template_name, new_name, manufacturer/model, and how source map keys bind to declarations.source_id remain unexplained.

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+resource: 'Preview or create a NEW user-defined PAN/OND from a complete exact template and cited values.' This is clearly distinguishable from generic component creation because of the template-plus-citation framing. However, it never names the nearest siblings (e.g. pvsyst_create_component) to make the boundary explicit.

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?

Gives a clear operating context: dry_run defaults to preview with no writes, and actual creation requires acknowledge_inherited_model=true. It also states the verification path ('Use a referencing native run to verify behavior'). It stops short of explicit when-not-to-use or naming alternative tools such as create_component.

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

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

No annotations exist, so the description carries the full burden. The phrase 'actually available in the installed CLI' usefully signals that results reflect live installation state rather than documentation, but it says nothing about output shape, whether calling it has side effects, or how to interpret missing commands.

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?

A single front-loaded sentence with no wasted words. The bracketed category prefix costs a few characters but aids grouping in a 77-tool inventory.

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 zero-parameter, no-output-schema introspection tool, the description conveys enough to call it and to know what kind of answer to expect. Slightly more detail on the return format (command names, option identifiers) would make it complete.

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?

The tool takes zero parameters, which is the baseline-4 case; the empty schema leaves nothing ambiguous. The description correctly implies no input is required.

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?

Specific verb (list) plus a clearly bounded resource (commands and option names available in the installed CLI). It is distinguishable from siblings like pvsyst_list_projects or pvsyst_license_info because it is self-introspection rather than an operational or license query, though it doesn't explicitly say so.

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 '[Setup & License]' prefix implies this is a discovery step early in a workflow, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. An agent can infer it should call this before attempting commands it is unsure about, but that is inferred, not stated.

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

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

With no annotations, the description carries the full burden. It does disclose a real constraint beyond structured data — 'only verified scalar fields are editable' — which tells the agent edits are restricted. It omits whether the source template is mutated, whether a duplicate new_name errors out, which library the clone lands in, and whether the operation is reversible.

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?

Three compact sentences, front-loaded with the action and followed by the key constraint, then the verification step. No filler, though the required-field sentence is slightly ambiguous in its naming.

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?

A five-parameter mutating tool with a nested object, no annotations, and no output schema needs more than this. The description never says what is returned (the new component identifier? the cloned field set?) nor explains source_library selection, which is the main behavioral unknown for a clone operation.

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% across five parameters, including a nested 'updates' object, so the description must compensate. It hints at edit scope ('verified scalar fields') and required naming fields, but the terms 'Manufacturer' and 'Model' do not map to any actual parameter name (component_type, source_name, new_name, updates, source_library), and the source_library default of 'workspace' is never explained.

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 ('Create a new text component from a complete existing template'), which makes it distinguishable from pvsyst_update_component and pvsyst_build_sourced_component. However, it never addresses the near-identical sibling pvsyst_copy_component, so an agent must infer the distinction from 'template' alone.

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 a clear post-creation verification workflow ('Run a simulation with a variant referencing the new component to verify it'), which is useful implied guidance. But it provides no when-to-use/when-not criteria versus pvsyst_copy_component, pvsyst_create_component, or pvsyst_clone_subarray, leaving the selection decision to inference.

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

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

With no annotations, the description must carry behavioral disclosure. It usefully states that embedded site/meteo snapshots and external component references are preserved, which is valuable context for a clone operation, but it omits key mutation behavior such as what happens if new_project already exists, whether source is modified, and any permission or failure semantics.

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?

Two short sentences, front-loaded with the core action and followed by preservation details. Every sentence adds useful information and there is no wasted wording.

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?

The description covers the high-level copy scope and preservation behavior, but for a mutation tool with no annotations, no output schema, and two required parameters with zero schema coverage, it leaves important gaps around identifier formats, overwrite behavior, and result expectations.

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% and the parameter titles are tautological ('Source Project', 'New Project'). The description does not add format guidance, naming requirements, or constraints for either required parameter, so it only weakly implies that source_project is copied into new_project.

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 gives a specific verb, resource, and scope: create a new project by copying an existing PRJ plus all its VC variants. It implicitly differentiates from pvsyst_create_project and pvsyst_clone_variant by mentioning copying the full project and all variants, but it does not explicitly name any sibling.

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?

Usage is implied by the copy semantics: use this when a full project and all its variants should be duplicated. However, the description does not explicitly say when to choose this over pvsyst_create_project or pvsyst_clone_variant, nor does it mention prerequisites or exclusions.

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

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.

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 non-obvious behavior: embedded site/meteo and external references are preserved rather than synchronized, inspect_project reports differences, and optional edits target specific subsystems. It still omits collision behavior, permissions, and what happens if new_variant already exists.

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 and every sentence adds some constraint or behavior. The prose is dense with jargon like 'VC' and 'PRJ', but it remains compact for a six-parameter tool with no schema descriptions.

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?

There are no annotations and no output schema, so the description must provide complete context. It covers preservation and edit-target semantics well, but it does not explain return behavior, collision handling, or required preconditions for creating a new variant.

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. It adds useful meaning for source_project defaulting and subarray_id strict integer typing, and clarifies that updates keys like PAN/OND/BTR/GEN target particular subsystems, but it leaves project, source_variant, and new_variant largely defined only by their names.

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 a specific verb and resource: 'Copy a variant as a NEW VC in project.' It distinguishes this from project-level cloning by emphasizing variant copying and cross-project import, so an agent can separate it from pvsyst_clone_project and pvsyst_clone_subarray.

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 explains the source_project default and the cross-workspace import case ('supply another workspace PRJ'), which implies usage context. However, it never names alternatives such as pvsyst_clone_project or pvsyst_create_* variant tools, so the agent must infer when this tool is preferred.

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

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

No annotations are provided, so the description carries full disclosure burden, yet it never says whether the operation is read-only, whether it mutates anything, what "bounded" means in practice (size limits, truncation), or what the result looks like. "Binary PAN hashes" hints at an opaque hash comparison rather than a field-level diff, but that is left for the agent to guess.

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?

A single compact sentence with the resource and both modes front-loaded; nothing is redundant. It is arguably too terse for the complexity involved, but no sentence is wasted.

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 four undocumented parameters, no annotations, and no output schema, the definition leaves major open questions (parameter meaning, result shape, side effects, limits). The two-mode framing is the only substantive content; for a comparison tool with this many unknowns, more is required.

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% and description adds almost nothing: it never explains `first`/`second` (paths? names? IDs?), what values `component_type` accepts, or — most importantly — what `second_library` (default "workspace") means, which implies components can be sourced from different libraries. Only the "same-type" constraint loosely maps to `component_type`.

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?

Uses a specific verb+resource ("Compare two ... components") and adds the key constraint that both must be the same type, plus the two comparison modes (text diff vs binary PAN hashes). It is distinguishable from siblings like pvsyst_get_component or pvsyst_validate_component, though it never frames itself against them.

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?

No statement of when to use this versus pvsyst_get_component, pvsyst_validate_component, or pvsyst_compare_engineering_scenarios (a similarly named sibling). The only implicit guidance is the "same-type" constraint. An agent must infer the use case from the name alone.

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

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

With no annotations, the description carries the full burden and does substantial work: preview is readonly, execution writes JSON/CSV/Markdown under Results without rerunning PVsyst, unbound historical results retain needs_review, missing columns stay missing, and it explicitly avoids claiming optimality or a single cause. It omits permissions, error behavior, and rate/scale limits, so not a 5.

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?

Front-loaded with the core purpose, then constraints, then side effects; nearly every sentence carries distinct information. It is dense and slightly jargon-heavy, but there is little pure waste.

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?

This is a complex tool with nested objects, no annotations, and no output schema, and the description covers outputs (Chinese explanations, key-hour differences), side effects, and limitations. However the 9-field nested scenario schema is essentially unexplained, so an agent still has gaps before it can populate scenarios correctly.

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 coverage is 0%, so the description must compensate and it only partly does: it explains the semantics of scenarios (2-3, baseline first, declared_changes) and dry_run (preview vs write), and implies objective and output_name. The nested EngineeringScenario fields (year, project, variant, csv_name, assumptions, run_manifest_name, nominal_dc_power_kw) get no explanation at all, leaving half the parameter surface undocumented.

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 names a specific verb and resource (compare two or three native result scenarios around an engineering question) and scopes the comparison to actual native columns. It is jargon-dense ('native result scenarios', 'engineering run manifests') but an agent can tell this apart from sibling read/simulate tools. It stops short of explicitly naming an alternative sibling.

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 supplies structural usage constraints (first scenario is baseline with no declared changes; two or three scenarios; each candidate declares changed input groups) and distinguishes preview vs execution via dry_run semantics. It never states when to prefer this over pvsyst_compare_components or pvsyst_read_results, so routing guidance is only implied.

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

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

No annotations are provided, so the description carries the full burden and it is a single line. 'NEW MET' implies a new file is written rather than an existing one being overwritten, but nothing is said about whether the source CSV/MEF/SIT are consumed or left intact, whether existing MET files are replaced, or what errors occur if a named input is missing.

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?

One sentence preceded by a bracketed domain tag, front-loaded and free of padding. Brevity is achieved partly by omitting information, but no sentence is wasted.

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?

This is a multi-file transformation with no annotations, no output schema, and zero parameter documentation, yet the description is one line. An agent could not reliably tell what the resulting MET contains or how timeshift affects the conversion.

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% and all six parameters appear as bare titles. The description only loosely implies the roles of csv_name/mef_name/sit_name/met_name through the sentence; it says nothing about timeshift, which is a meaningful integer offset with default 0, or about log_level.

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+resource: convert a staged CSV plus MEF (Meteo) and SIT (Sites) into a new MET file. That is concrete enough to distinguish the transformation from pure read tools like inspect_weather_csv. It stops short of naming which siblings to use instead, so 4 rather than 5.

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 statement of when to use this versus pvsyst_prepare_weather, pvsyst_acquire_weather, or pvsyst_build_monthly_weather, all of which sit in the same weather pipeline. The word 'staged' hints at a prerequisite state but the prerequisite is never spelled out.

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

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

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the non-overwrite guarantee, preservation of legacy PAN bytes, and the two possible source libraries, but says nothing about what happens on a name collision (error vs rename), permission/read-only constraints on the builtin source, or what the operation returns.

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?

Three short sentences, front-loaded with the action and scoping constraint, with no filler. The telegraphic style and unexplained acronyms (PAN/OND/BTR/GEN) cost a little readability.

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 and no output schema, the description covers the most important behavioral facts (no overwrite, legacy bytes kept, source library options). It still leaves an agent without conflict-handling behavior, return content, or a clear reason to prefer it over clone_component.

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 all four parameters are undocumented in the schema. The description partially compensates by expanding the component types to PAN/OND/BTR/GEN and by describing source_library's accepted values, but source_name and new_name semantics and any naming rules for new_name remain unstated.

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 (copy) and resource (component) with scope: into the workspace, no overwrite, legacy PAN bytes preserved. The bracketed [Components] tag helps group it. However, it never distinguishes itself from the sibling pvsyst_clone_component, which reads as a near-synonym in this toolset.

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 'without overwrite' constraint and the note that the source library can be workspace or the read-only builtin imply intended usage and prerequisites, but the agent is left to infer when to use copy_component versus clone_component. No explicit when-to-use, when-not-to-use, or alternative routing is given.

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

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

With no annotations, the description carries the full load and does so substantively: preview writes nothing, execution creates exactly one new VC, custom resistance and mixed source cables are blocked, length rounding is rejected, and active vs inactive source inheritance rules are disclosed. The disclosures are real behavioral context, though the run-on phrasing makes several of them hard to parse reliably.

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?

Content is mostly substantive but presented as one undifferentiated block with run-together tokens ('recorded8.1.6', 'exactly0.1m') and a bracketed tag eating the front-loaded slot. A reader must parse three or four times to extract the same facts that could be stated in clean, ordered sentences.

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 7-parameter mutation-style tool with no annotations and no output schema, the description covers version gating, blockers, and inheritance rules, but leaves the naming contract (new_variant vs variant_name), the shift/replace consequence of writing into an existing path, and what preview versus execution actually return. 'recorded8.1.6' and 'Saving is not native consumption' are opaque without internal context.

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 largely does: length_m constraints (positive, <=100000, exactly 0.1 m representable, not rounded), metal/section inheritance from active vs inactive sources, and the BOM flag are all explained beyond the bare schema. Gaps remain for variant_name vs new_variant and the project/source_variant fields, which are only obliquely referenced.

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+resource: 'Preview or create a NEW VC with native uniform per-inverter AC cables,' which is enough for an agent to know the outcome. However, 'VC' is unresolved jargon (presumably variant configuration) and the description never explicitly contrasts itself with the obvious sibling pvsyst_create_native_dc_cabling_variant, so sibling routing relies on inference from the tool name.

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 eligibility envelope is spelled out ('PV-only single fixed plane/subarray', no MV/HV/load/storage/P50/horizon/active geometry), which effectively defines when the tool can be used. But it never names an alternative tool or says use X instead of Y, and the one alternative mention ('Getter ac_cabling exposes stored state ... for read/re-edit') is a hint rather than an explicit directive.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that the tool validates structure, required fields and 'known hazardous numeric values,' and honestly bounds the guarantee ('only a referencing simulation verifies physics'). It does not disclose what happens on filename collision, whether an existing component is overwritten, or what is returned — gaps that matter for a no-annotation 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?

Three tight sentences with a front-loaded category tag and the core action first; the validation caveat and the binary-PAN exception follow logically. No filler or restated title.

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?

There are no annotations and no output schema, so the description is the only documentation for a 3-parameter file-creating mutation, and it omits return value/identifier, filename handling, and failure modes. What it does cover (format, validation scope, alternative route) is solid but not sufficient on its own.

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 coverage is 0%, so the description must compensate, and it partially does: it names the accepted component_type values (PAN/OND/BTR/GEN) and specifies that content is full UTF-8 PVObject_ text. However, filename — the third required parameter — is never explained (path basis, extension, overwrite behavior), leaving a required input undefined in both schema and description.

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 gives a specific verb + resource ('Create a NEW PAN/OND/BTR/GEN') and pins the input format precisely ('complete UTF-8 PVObject_ text in the workspace without a template'). It explicitly separates itself from pvsyst_copy_component for legacy binary PAN, though it does not distinguish itself from the similarly-scoped sibling pvsyst_build_sourced_component.

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 states a concrete precondition (content must be 'complete' UTF-8 PVObject_ text) and an explicit exclusion with an alternative: 'Legacy binary PAN must be imported with pvsyst_copy_component instead.' It stops short of saying when to prefer this over creating via template/build_sourced_component, so a small inference remains.

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

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

No annotations exist, so the description carries the full burden and does so thoroughly: dry_run=true writes nothing, execution creates exactly one NEW VC and never edits the source PRJ/VC, weather, topology or hardware, reusing existing locking, path checks, read-back verification and no-overwrite semantics. It also discloses write scope precisely (only NStrOrient1 plus optional root Comment; NoOrientation2 unchanged; no other record created or copied) and flags that native_consumption_verified stays false.

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, but the remainder is a dense run-on with nested parentheticals enumerating raw template internals (FieldType values, BTNoTrackers=-1,-1, Flags=$00, Version=8.1.6) that read like spec-sheet minutiae rather than decision-relevant guidance. No line breaks, bullets, or grouping, so an agent must parse ~250 words of prose to extract the actionable constraints.

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 7-parameter, high-complexity mutation tool with no annotations and no output schema, the coverage is unusually complete: validation rules, write scope, dry-run behavior, and the residual verification caveat are all present. The remaining gap is that three parameters (project, source_variant, new_variant) are never explicitly defined and no return-value shape is described.

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 coverage is 0%, so the description must compensate, and it does for the non-obvious parameters: first_orientation_strings is bounded to 1..39 (explicitly an adapter bound, not a native limit), dry_run is defined as write-nothing, variant_name/add_utf8_bom are tied to display-name and BOM rules, and the Comment is called optional. project, source_variant and new_variant are only implicitly explained (source is never edited, new VC is created), which keeps this short of a 5.

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?

Opens with a specific verb and resource: 'Preview or create a NEW variant that rebalances an existing two-face Dome allocation.' That is unmistakably distinct from sibling variant creators (tracking, AC cabling, shed geometry, MV night disconnect), so an agent can route correctly without opening the schema.

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?

Gives strong preconditions and exclusions: the source must be an already-allocated native 8.1.6 Dome template with one subarray on both faces, and 'a source without an existing allocation is refused rather than completed'; unknown, duplicated, missing or wrongly paired records stop. What it lacks is any explicit pointer to the sibling to use instead when the source is not a Dome allocation (e.g., clone_variant or another variant creator).

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

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

With no annotations, the description carries the behavioral burden well: it states no defaults are inferred, describes binding prepared records, enabling flag bits, retaining other flags, creating only one new VC, never editing the source, not simulating, and adding a BOM for non-ASCII paths. It still does not explain dry_run behavior, failure modes, or return values.

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 technical jargon with many tightly packed clauses. Much of the content is substantive, yet it could be structured more clearly and would benefit from trimming or bullet-like separation.

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?

This is a complex nine-parameter mutation with no annotations and no output schema, so the description needs to be comprehensive. It provides rich behavioral and nested-field context, but leaves key operational details like dry_run semantics, return behavior, and several top-level parameter meanings under-specified.

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%, and the description compensates for many nested fields by naming series/parallel counts, monthly temperatures, SOW, SOC fractions, power limits, efficiencies, and availability requirements. However, top-level parameters such as project, source_variant, new_variant, dry_run, and load_manifest_name are left mostly implicit.

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 a specific verb and resource: preview or create a new native AC-coupled storage VC from an existing PV-only Grid design. It also distinguishes the operation from hybrid DC battery-port modelling and grid-charge tariff control, though it does not explicitly name sibling tools.

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 context is clear: use this for an AC-coupled native storage variant from a PV-only Grid design, with explicit requirements for WeakGrid availability. It includes some exclusions such as not being a hybrid DC model, but it does not name alternative sibling tools or state when to prefer them.

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

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.

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

With no annotations, the description carries the full burden and discloses extensive behavior: execution writes only UserData/<output_name>.pvc2 with no-overwrite semantics, dry_run=true writes nothing, source variant and PAN bytes are re-checked, native project/variant/PAN bytes are never modified, and native_consumption_verified/imported stay false. It also documents ceilings, validation limits, and beta caveats, making the write operation's scope and side effects unusually clear.

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 description is an extremely long, dense paragraph with many interleaved constraints, repeated ideas, and no bulleted structure. Although the purpose is front-loaded, the volume and lack of organization make it hard to scan and retain.

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 the tool's complexity, absence of annotations, and lack of an output schema, the description is quite complete: it covers source prerequisites, mesh versus table modes, dual-plane restrictions, write behavior, and validation limits. It does not fully describe the response shape beyond mentioning structured diagnostics and disclosed tilt/azimuth, leaving a minor 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?

Top-level schema description coverage is 0%, so the description must compensate. It explains house.kind='mesh' versus legacy house, layout.origin_m and layout.roof_mesh, named tables with orientation_id, module_geometry fallback, and dry_run semantics, adding substantial meaning beyond the schema; project, variant, and output_name remain self-explanatory but are not explicitly described.

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: "Write a complete AI-authored house/PV scene in one call," and immediately recommends house.kind='mesh'. It distinguishes mesh authoring from legacy template authoring and hints at import status, though it does not explicitly name sibling tools like pvsyst_import_house_pv_scene.

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 mode-selection guidance (prefer mesh, use layout.origin_m and layout.roof_mesh for mesh houses, alternatively layout={tables...}, and "do not mix" legacy layout with mesh mode). However, it never says when to use this tool versus the many sibling tools, so an agent must infer tool routing from context.

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

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

With no annotations, the description carries the full burden and does so: dry_run writes nothing, execution only creates a new VC (never overwrites), source VC/PRJ/CSVs untouched, no renormalization/filling/DST shift, leap-day handling, base62 DDMM encoding with returned precision, BOM disclosure for non-ASCII paths, and hard stops on legacy/ambiguous VCs. This is unusually rich disclosure of side effects and failure modes.

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?

Purpose is front-loaded, but the body is a dense run-on packing multiple distinct constraints per sentence, plus some lower-value assertions ("reading-progress logs do not prove native consumption"). No structure or grouping to help an agent scan for the rules that matter.

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 side effects, failure modes, and even a partial return detail (encoding precision). The main gap is per-parameter semantics and any statement of the returned VC/variant shape.

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 coverage is 0% and no property has a description, so the description must compensate for all five parameters. It explains dry_run and gives meaningful context for load_manifest_name (a prepared manifest in Results, not an absolute path), but says nothing about project, source_variant, or new_variant — three of four required params remain undefined.

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: preview/create a NEW variant with an explicit embedded hourly load snapshot, and explicitly scopes it against alternatives ("This sets loads, not battery dispatch or hybrid ports"). It doesn't name the nearest siblings (pvsyst_create_native_load_variant, pvsyst_prepare_load_profile), but the operation is unmistakable.

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?

Clear context for when to call it (bind a prepared v1 load manifest in Results to current CSVs) and when not to (don't treat config as consumed until E_User is verified in a native run; a later CSV edit needs a new binding). Lacks explicit routing to a named alternative tool for the overlapping load-variant use cases.

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

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: preview writes nothing, execution retains source/snapshot/no-overwrite protections, only the night-disconnect bool and dependent bit change, and all unrelated inputs are inherited. It also discloses blocked cases and clarifies that configuration never claims native consumption.

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 description is dense but front-loads the core purpose and then layers constraints and safety behavior. Given the complexity, most sentences carry necessary technical information, though the jargon-heavy phrasing and run-on constraint list reduce readability.

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 is quite complete on preconditions, blocked configurations, inheritance behavior, and preview/write protections. It stops short of explaining what a successful execution or preview returns, which is a remaining 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?

Schema description coverage is 0%, so the description must compensate. It adds meaningful hints for key parameters, such as night_disconnect, source/candidate variants, preview/dry-run behavior, and optional name/BOM, but it does not explicitly define all seven parameters or their accepted values, leaving interpretation partly to the schema names.

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 a specific verb and resource: creating a new VC that changes the recorded MV night switch. It clearly distinguishes this specialized variant from other create-variant siblings through the MV night-disconnect scope and the preview/exclusive-create behavior.

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 gives substantial usage context: native8.1.6, PV-only single fixed plane/subarray, valid circuit counts, and the recorded single-MV20kV profile are required. It also lists blocked configurations such as HV/multiple transformers, custom loss tables, loads/storage/P50/horizon/active geometry, but it does not name alternative tools or explicitly compare when to use them.

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

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

With no annotations, the description carries full burden and discloses many behavioral traits: dry_run reads state without activating/typing, failure can leave a new file/current modal with path disclosed, saving is not simulation consumption proof, native SaveAs chooses the new VC id, variant_name is a display title, and BOM/display comments may normalize. It also lists prohibited actions (no application start/exit, INI edit, clipboard, external DC formula, private VC patch).

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 content is dense and front-loaded with the core action, but it reads as a single wall of text with non-standard abbreviations and nested clauses. While many sentences earn their place by conveying constraints, the lack of structure (bullet points, separate paragraphs) makes parsing harder than necessary.

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 the tool's complexity (6 parameters, no output schema, no annotations, 0% schema coverage), the description is remarkably complete. It covers prerequisites, mode semantics, failure modes, file handling, prohibited operations, and scope exclusions. Nothing an agent needs to call it correctly appears to be missing.

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. It defines value constraints for dc.value (finite, nonnegative, exact 0.01 precision, <=20 characters; percent<=100) and clarifies that variant_name is a display title while 'Native SaveAs chooses the new VC id'. It also explains dry_run and confirm behavior. However, the 'project' and 'source_variant' parameters are only indirectly addressed through the alignment requirement, leaving slight ambiguity.

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: 'Set native DC resistance(mOhm) or STC loss(%)'. It distinguishes itself from sibling variant-creation tools by listing what it does not handle (AC/MV/HV/load/storage/geometry/horizon/P50), which effectively scopes its domain. However, the dense parenthetical constraints and jargon slightly obscure the core action.

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 explicitly states preconditions ('operator must have the matching project open and DataPath equal to the MCP workspace'), mode selection ('dry_run only reads... Actual input requires dry_run=false AND confirm=true'), and exclusions ('No application start/exit, INI edit, clipboard...'). It clearly tells the agent when to use dry-run versus actual input and what not to do.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses exactly what is written (bit19, pvLoad, optional Comment), what gets replaced in place, locking/path/read-back/no-overwrite semantics, and the honest caveat that native_consumption_verified stays false pending manual E_User/PDF verification.

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?

Purpose is front-loaded, but the body is a dense wall of run-on clauses that is hard to scan. Most sentences carry real information, yet the volume and lack of paragraph breaks make it heavier than necessary for the 7-parameter surface.

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 mutation tool with no annotations and no output schema, the description covers modes, validation, side effects, failure modes, BOM handling and verification caveats comprehensively. Nothing an agent needs to call it correctly appears to be missing.

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 coverage is 0%, so the description must compensate and largely does: it explains mode as the discriminator, constant_kw units and positive constraint, monthly twelve-kWh semantics, daily 24 hourly powers plus trailing sum slot, dry_run, add_utf8_bom interaction with variant_name, and strict numeric validation 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?

States a specific verb (preview or create) and resource (a NEW variant with one native flat load block) and enumerates the three modes and the exact supported structural subset. An agent can distinguish it from generic load-profile siblings by the 'native flat block' / constant|monthly|daily framing.

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?

Clearly indicates dry_run=true writes nothing and execution creates a NEW VC without touching the source, and names failure conditions (HourlyFile, Probability, HouseHold, duplicated-owner blocks stop). It does not explicitly compare against pvsyst_create_load_variant or pvsyst_prepare_load_profile, leaving some sibling routing to inference.

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

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

With no annotations, the description carries the full burden and does so extensively: dry_run writes nothing, execution creates exactly one NEW VC and never edits the source PRJ/VC, store locking/path checks/read-back verification/no-overwrite semantics are reused, and unsupported sources stop rather than being overwritten. It also explicitly discloses many non-goals, including that it does not change grid power limitation or power factor and does not prove consumption of the created variant.

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 extremely dense and runs to several hundred words in long paragraphs, mixing actionable rules with deep native-profile details such as root Flags values and exact strategy strings. Much of this may be necessary safety context, but the lack of structure and the volume make it hard to scan for an agent that mainly needs the mode discriminator, dry-run behavior, and parameter meanings.

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 is rich on safety, eligibility, and non-goals, but it omits what the preview or creation returns and does not fully define all seven inputs. It is more complete than average, yet still leaves gaps that matter to correct invocation.

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 for seven parameters. It gives useful semantics for discharge.mode, after_sunset vs hour_window, start_hour/end_hour bounds (0..23), and dry_run, but project, source_variant, new_variant, and add_utf8_bom are only implied or discussed vaguely as 'existing display-name and BOM rules'. It partially compensates but leaves several required string parameters unexplained.

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 a specific verb and resource: preview or create a NEW variant that switches the native PeakShaving discharge strategy. It clearly identifies the niche (PeakShaving discharge strategy variant), which effectively distinguishes it from generic variant-creation or update tools in the sibling list, though it does not explicitly name an alternative tool.

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 describes the supported subset and blocking conditions (e.g. no load, P50/P90, saved horizon, explicit 3D scene, or module layout), which implies when the tool is applicable. However, it never says when to use this tool instead of alternatives such as pvsyst_update_variant_parameters or pvsyst_create_grid_storage_variant, leaving the choice mostly to inference.

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

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

No annotations are provided, so the description carries the full burden, and it does: content-preservation guarantees (BOM/newlines/references), rejection rules (existing same-prefix members, duplicate normalized IDs), partial-failure semantics ('handled write errors remove only created files'), and validation scope limits ('checks envelopes and subarray sections, not full schema or physical validity'). This is exactly the mutation-risk disclosure an agent needs.

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?

Front-loaded with the core action, then constraints and guarantees in descending priority. Dense and largely waste-free, though a few clauses are telegraphic ('Site/meteo/components remain external') and would read better split out.

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?

No output schema exists, and the description usefully closes that gap with 'Returns the member hash map.' It also bounds scope and names next steps. Minor gaps remain: the meaning of the 'project' argument and where the created files land are not stated.

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 coverage is 0%, so the description must compensate. It does well for two of three: 'variants maps VC identifiers to their full text; 1..127 variants' and project_content as complete UTF-8 text. The 'project' parameter is only obliquely characterized through 'same-prefix,' leaving its role (name/prefix) partly inferential.

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: 'Create a NEW PRJ/VC set from complete UTF-8 text without an existing project.' The precondition ('without an existing project') plus the bracketed domain tag distinguishes it from pvsyst_open_native_project, pvsyst_clone_project, and pvsyst_prepare_design_project.

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?

Gives a clear applicability condition (no existing project; caller supplies full text) and names the follow-up path: 'inspect, validate and simulate the new project.' It does not explicitly name a sibling alternative for the contrasting case (e.g., clone/open when a project already exists), so the routing is implied rather than spelled out.

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

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.

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

With no annotations at all, the description carries the full burden and does partially deliver: it discloses required PVsyst version (8.1+), the two filesystem locations written to, and the external-service network lookup that may occur. It omits overwrite/collision behavior for an existing .sit, permission or license prerequisites, and whether the operation is reversible — significant gaps for a file-creating mutation.

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?

Three short sentences, front-loaded with the action and the artifact path, and the conditional network behavior is placed last where it belongs. The bracketed category tag and 'CLI create-site' phrasing add minor noise but no real bloat.

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 12-parameter, 5-required mutation with no annotations, no output schema, and zero schema descriptions, the definition covers the environment and side effects but leaves the argument contract essentially undocumented. An agent cannot reliably populate weather_csv_name, sit_name vs site_name, or the optional locale fields from this description alone.

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% across 12 parameters, so the description must compensate and largely doesn't. It explains only the omission behavior of altitude, timezone and country; it says nothing about albedo, region, source, log_level, weather_csv_name format, or the critical and confusing distinction between the required site_name and sit_name.

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 (create a NEW SIT via CLI create-site) and names the exact output location (workspace/Sites, PVsyst 8.1+), plus the side effect of staging a weather CSV in workspace/Meteo. It's clear what the tool does, but it never distinguishes itself from the weather/data siblings such as pvsyst_acquire_weather or pvsyst_build_monthly_weather that also populate workspace/Meteo.

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?

Usage is implied (create a site when it does not yet exist) and one useful conditional is given: omitting altitude/timezone/country triggers a possible external lookup. However, there is no explicit guidance on when to prefer this over resolving a location or acquiring weather first, nor any warning about creating a site that already exists.

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

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.

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

With no annotations, the description carries the full burden and mostly meets it: it discloses that a NEW ZIP is created, what is bundled versus left as external dependencies, that no certification or review-status change occurs, and that existing ZIPs block the operation rather than being overwritten. It omits where the ZIP lands and what permission or environment constraints apply.

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?

Content is front-loaded with the core action in the first sentence and every clause carries information about ZIP contents or constraints. The middle sentences are long and list-like, but there is little pure filler.

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 file-producing mutation tool with no annotations, no output schema, and 0% parameter coverage, the description covers contents and non-overwrite behavior well but leaves the caller without the returned artifact path or the exact semantics of output_name. An agent would still have to guess part of the call contract.

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. It effectively explains manifest_name (one workspace run manifest), comparison_name (bound scenarios plus Chinese comparison report), and dry_run ('Preview writes nothing'), but output_name is never explained (naming rules, overwrite behavior of the new name) and no default or format guidance is given.

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 gives a specific verb and resource: package a completed engineering run as a new local Results ZIP, and enumerates what the ZIP contains. It distinguishes itself from review-type siblings by stating 'Export does not certify the design or upgrade a review status', but it never names the closest alternatives (pvsyst_project_handoff, pvsyst_review_engineering_brief, pvsyst_export_logs).

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?

Usage is only implied: the input must be a 'completed' run manifest with a valid input/output binding. The 'Preview writes nothing; existing ZIPs stop' clause hints at a preview-then-commit workflow, but there is no explicit when-to-use or when-not-to-use guidance versus the other export/handoff tools.

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

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

With no annotations, the description carries the burden and does meaningful work: it discloses that a ZIP file is written to a specific directory, warns the archive may contain private data, and clarifies that only the path is returned rather than the contents. It does not mention permissions or whether an existing archive is overwritten, keeping it just below a 5.

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?

Two sentences, both earning their place: the first covers action and destination, the second covers the privacy caveat and return shape. Front-loaded with the action and no filler.

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 parameterless, non-destructive export with no output schema, the description covers destination, artifact type, privacy risk, and return value. Only the overwrite/conflict behavior and any size or permission constraints are left unstated.

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?

The tool takes zero parameters, so the baseline is 4; there is nothing further for the description to disambiguate beyond noting the fixed output location, which it does.

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 (export) and resource (CLI diagnostic logs) plus the exact output artifact and destination (ZIP under workspace/Results). No sibling tool exports logs, so the agent can identify it immediately from name plus description.

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 '[Setup & License]' tag implies a diagnostic/troubleshooting context, but the description never says when to reach for this versus other setup tools like pvsyst_capabilities or pvsyst_license_info. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the burden itself and does a substantial job: it discloses paging, returned data categories, curve CSV behavior, error reporting for omissions, and several important caveats about unverified coefficients, per-MPPT limits, and IDCMax=0. It does not discuss permissions or side effects, but the read-oriented framing and data caveats are unusually detailed.

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 description is a dense, jargon-heavy block with eight sentence-like clauses and poor front-loading. Some details are useful, but the lack of structure makes it hard to scan and the opening does not orient the agent before diving into specialized return semantics.

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?

There is no output schema and no annotations, and while the description explains many return-side caveats, it omits essential caller information such as accepted component_type values, filename conventions, and why to use this tool rather than list_components or validate_component. The result is incomplete for a six-parameter tool with 0% schema coverage.

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% for six parameters, so the description needs to compensate, but it only explains include_curve_csv and vaguely implies paging. It never clarifies component_type allowed values, filename expectations, library semantics, or offset/limit behavior.

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 makes clear that this tool reads component-file internals, including text, allowlists, SHA, curve paths, field units, and remarks. The verb-and-resource combination is specific enough to separate it from a generic list or simulation tool, though it does not explicitly contrast itself with siblings like pvsyst_list_components, pvsyst_validate_component, or pvsyst_compare_components.

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 gives caveats such as 'static inspection does not verify simulation behavior' and 'CSV export does not expand edit support,' but these are limitations rather than when-to-use guidance. It never says when an agent should choose this over list_components, validate_component, compare_components, or project_components.

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

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

No annotations, so the description carries the burden; it does disclose the read nature and that the payload includes a SHA-256 for optimistic concurrency, which is genuinely useful. It omits failure behavior (e.g., what happens if the variant is missing or the hash is stale) and permission requirements.

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?

A single front-loaded sentence with a category tag and no filler; the purpose lands immediately. Slightly terse given the schema gaps, but nothing is wasted.

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 two-parameter read with no output schema and no annotations, the description covers what is returned at a high level (component refs plus hash) but leaves parameter semantics and error behavior unaddressed. Adequate but with visible gaps.

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 coverage is 0% and the description says nothing about the two parameters. 'project' and 'variant' are self-explanatory identifiers, but there is no indication of accepted formats, whether names or IDs are expected, or whether project must already be open.

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 (Read) and resource (component references in a variant) plus a concrete return element (current SHA-256). This is distinguishable from pvsyst_get_variant_parameters and pvsyst_update_variant_components, though the description never explicitly names those siblings.

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?

'for guarded edits' implies the usage context — fetch the hash before mutating so an edit can be validated — but the description never states when to call it versus alternatives or what the guard precondition is. Usage is inferred rather than spelled out.

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

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 clarifies read-only status, raw vs computed fields, omitted/malformed fields, unsupported system forms, units such as degC and W/m2/K, and that stored_consistent does not imply verified geometry. It lacks prerequisites and auth needs, but exposes substantial operational caveats.

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 description is a dense, semicolon-heavy block with no front-loaded summary and long tangential field enumerations. It is information-rich but poorly structured and likely to obscure the main purpose.

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, the description usefully enumerates many returned fields and caveats, which is valuable for a complex inspection tool. However, it omits input parameter semantics and lacks a concise high-level orientation, leaving clear gaps.

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% and both required parameters (project and variant) are completely undocumented in the description. The description adds no meaning about identifier formats, expected values, or selection rules for these inputs.

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 says 'Inspect orientations...' and then enumerates many variant parameter fields, so the resource is identifiable, but there is no single concise statement of overall purpose. It distinguishes from write tools only obliquely with 'read-only here, not a mode editor' and 'does not widen write support'.

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 or when-not-to-use guidance, and no sibling tool is named as an alternative. The mention of read-only behavior implies inspection rather than editing, but an agent must infer the selection criteria.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: dry_run reads state only, execute requires dry_run=false and confirm=true, no automatic retry/source overwrite/app start/exit/INI modification occurs, failures leave the window for inspection, and clipboard use is tightly scoped. It also discloses native-method behavior, verification flags, and the fact that native consumption remains unverified until a separate simulation.

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 description is dense and largely front-loaded, but it is a single long paragraph with repeated dry_run/flag explanations across GUI and native modes. Much of the length is justified by tool complexity, but the structure could be clearer and less repetitive.

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 tool with no annotations and no output schema, the description covers prerequisites, failure modes, side effects, verification flags, and the next simulation step. It does not fully enumerate the return shape, but it provides enough context for an agent to call the tool correctly.

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 for all six parameters. It explains method, dry_run, confirm, shading_mode, and variant_name constraints well, and gives enough context for scene_name indirectly, though some parameter-level format details remain implicit.

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 a specific verb and resource: importing a generated house/PV scene, with both GUI and native method modes. It clearly distinguishes import behavior from variant creation, but it does not explicitly name a sibling such as pvsyst_create_house_pv_scene to route the agent between them.

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 gives strong usage context: an already open native PVsyst GUI, matching workspace and recipe project, bounded Windows/version assumptions, one- or two-region support, and opt-in method='native' limitations. It also directs post-import simulation to pvsyst_run_simulation, though it lacks a direct comparison with create_house_pv_scene.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses caveats around project_name UTF-8 root-header reading and utf8_bom PRJ marker reporting, but it does not explicitly state read-only safety, permissions, or return format.

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 description is compact and front-loads the main inspection purpose. The technical caveat about UTF-8 BOM handling is relevant but slightly cryptic, and the bracketed category tag is incidental.

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 and no output schema, the description should fully explain both input and output. It names several output artifacts (hashes, references, missing-file flags, differences) but leaves the 'project' input undefined and does not describe the overall return shape.

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?

The sole input parameter 'project' has 0% schema description coverage, and the description does not define what value it expects (path, name, hash, etc.). The mention of 'project_name' appears to describe output or header behavior rather than the input parameter.

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 clearly states that the tool lists PRJ/VC hashes and embedded SIT/MET references, flags missing workspace files, and compares project vs. variant sources. This is a specific inspection action, though it does not explicitly distinguish the tool from similar diagnostic siblings such as pvsyst_review_project_inputs.

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 no explicit guidance on when to use this tool versus alternatives, nor does it state prerequisites or exclusions. It only implies diagnostic inspection through phrases like 'flag missing workspace files' and 'differences'.

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

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

No annotations exist, so the description carries the full burden and does so well: it declares read-only behavior, enumerates exactly what is reported (metadata/units, gaps, duplicates, bad numbers, monthly irradiation/temperature, SHA-256), and states hard input constraints (GHI/Tamb required, whole-year 00:00..23:00 including leap day, no silent filling or time conversion). It does not say how a non-conforming CSV surfaces (error vs. findings payload), which keeps it below a 5.

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?

Purpose and read-only nature are front-loaded, then constraints, then validity scope; nearly every sentence carries information. It is dense but not padded, with only minor redundancy between the whole-year timestamp rule and the 'valid covers this CSV profile only' caveat.

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?

Behaviorally rich for a no-annotation, no-output-schema tool, but an agent still cannot determine what the two arguments mean or how results/failures are returned. Adequate to decide whether to call it, incomplete for calling it correctly.

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% for both parameters and the description never mentions them. 'csv_name' is left ambiguous (bare filename vs. path/location) and 'expected_year' is never explained at all, despite the whole-year requirement implying its role. With zero schema documentation, this is a material gap the description needed to close.

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 ('Check a PVsyst standard hourly CSV in Meteo') plus the moment of use ('before preparing a full-year run'). It also draws an explicit scope boundary against sibling concerns ('not MEF/SIT matching or native MET correctness'), so an agent can separate it from review_weather/prepare_weather without opening the schema.

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?

Gives clear when-to-use ('before preparing a full-year run') and when-not ('valid covers this CSV profile only, not MEF/SIT matching or native MET correctness'), plus a routing hint that POA/time-reference cases 'need separate review'. What it lacks is naming the actual alternative tools an agent should call instead.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the confirm=true requirement and a genuine operational risk (MCP clients may retain arguments containing license keys), but says nothing about whether activation is reversible, whether the key is consumed, error/failure behavior, or rate limits.

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?

Two short sentences with no waste: the action and its gating requirement come first, with the security caveat trailing as supporting context.

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 mutation tool with no annotations and no output schema, the description should also indicate what happens on success or failure and how the license state changes. It covers the safe-invocation essentials (key, confirm, key-handling caution) but leaves the outcome side unspecified.

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% and the schema does not even mark 'confirm' as required, so the description adds real value by stating that confirm=true is mandatory. 'Key' is identified as the license key, covering the second parameter's meaning; only format details are missing.

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 ('Activate a CLI license') plus the input it consumes ('using a supplied key'). The 'CLI license' scope cleanly separates it from the license_info, license_deactivate, and license_sync siblings.

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 activation intent implies when to use it, but there is no explicit guidance on prerequisites or alternatives — e.g., whether to check pvsyst_license_info first, or what to do if a license is already active. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It discloses the confirm guard, which is genuine behavioral context, but says nothing about irreversibility, what happens to an in-use license or running simulations, or whether the license can be reclaimed afterwards.

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?

Two short sentences, front-loaded with the bracketed category and action, with zero filler. Nothing could be removed without losing meaning.

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 annotations, no output schema, and no parameter documentation in the schema, the description needs to do more: it omits customer_id, the return/result of deactivation, and the consequences of the operation. An agent has enough to attempt the call but not enough to do so safely.

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 for both parameters. It explains that `confirm` must be true, but the required `customer_id` parameter is never mentioned or explained, leaving the most important input undocumented.

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 a specific verb ('Deactivate') and resource ('this computer's CLI license'), and the scoping to the local machine implicitly distinguishes it from the sibling pvsyst_license_activate. It stops short of naming that sibling or explaining the lifecycle relationship, so it is clear but not fully differentiated.

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?

'Requires confirm=true' gives one concrete prerequisite for invocation, which is useful. However, there is no statement of when to deactivate versus re-activating (pvsyst_license_activate) or syncing (pvsyst_license_sync), nor any warning about when not to use it.

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

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

With no annotations, the description carries the full burden, and it does add one genuinely useful disclosure: keys and Host ID are intentionally withheld from the response. However, it says nothing about whether the CLI must be running, whether the call requires authentication, or what happens if no license is present.

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?

A single dense sentence with the scope caveat front-loaded; nothing is wasted. The '[Setup & License]' prefix is mild redundancy against the tool name, which keeps it just short of a 5.

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?

There is no output schema, so the description must hint at return contents, and it only names 'state and quota' without any shape or field detail. For a zero-parameter, no-annotation tool this is serviceable but leaves the agent guessing what it will get back.

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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies.

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: 'Read CLI license state and quota.' The sibling set (license_activate, license_deactivate, license_sync) makes the read-only variant distinguishable, though the description never explicitly contrasts itself with those siblings.

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?

Usage is only implied by the word 'Read' and the bracketed '[Setup & License]' tag. The description gives no explicit when-to-use guidance, no prerequisites (e.g., does the license need to be activated first?), and no reference to the sibling license_* tools that an agent must choose between.

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

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

With no annotations, the description carries the full burden, and it does disclose that the operation contacts a server (a network-touching action) and that a confirm flag gates it. However, it does not say what state changes locally, whether the sync is idempotent, what happens on server unreachability, or what permission is required.

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?

Two short sentences with the purpose first and the gating requirement second — no filler. It could front-load the confirm requirement alongside the action, but it is efficiently sized.

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 state-changing license operation with no annotations and no output schema, the description omits the effects, error/confirmation behavior, and post-conditions an agent needs before invoking it. The single boolean parameter makes the schema simple, but the behavioral picture remains thin.

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 coverage is 0%, so the schema alone only shows 'confirm' as a boolean defaulting to false. The description adds the crucial semantic that it must be set to true, but does not say what occurs when it is false (error, no-op, or dry run).

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 (Synchronize) and resource (CLI license information with its server), and the bracketed category separates it from project/variant tools. It is distinguishable from the license siblings (info/activate/deactivate), though it never explicitly says how it differs from them.

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?

'Requires confirm=true' is a prerequisite, not usage guidance. There is no statement of when to call this versus pvsyst_license_info, pvsyst_license_activate, or pvsyst_license_deactivate, and no exclusions or preconditions (e.g. license must already be activated, network available).

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

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

With no annotations, the description carries the full burden. It usefully discloses that the encrypted built-in component database cannot be enumerated, which prevents a wasted call. It omits pagination behavior (limit/offset defaults), result format, and any permission constraints a mutating-adjacent tool might have.

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?

Two compact sentences with no filler, and the scope/limitation is front-loaded. It is efficient, though it could trade one clause for the missing parameter guidance.

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 5-parameter list tool with zero schema descriptions, no annotations, and no output schema, the description is too thin. An agent cannot tell how query filters, how limit/offset paginate, or what the returned records look like.

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 coverage is 0%, so the description must define all five params. It only clarifies component_type values (PAN/OND/BTR/GEN) and the workspace-vs-DataRO source choice (library). The required component_type is unexplained as to case/format, and query, limit, and offset are entirely undocumented.

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 (List) and the exact resource domain (PAN, OND, BTR or GEN loose component files) in workspace or DataRO. This clearly distinguishes it from get_component, create_component, and list_projects siblings, though the name alone ('list_components') would not have conveyed the file-type specifics.

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?

Implicitly scopes usage to workspace or installed DataRO and rules out the built-in database ('not enumerable'), which is useful when-not guidance. However, it never names alternatives (e.g., get_component for a single component) or explains when to prefer one source over the other.

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

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

With no annotations, the description carries the full burden, and it does disclose the key constraint that results are limited to the configured workspace. It says nothing about what happens when no workspace is configured, whether paths are absolute or bare filenames, ordering, or pagination.

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?

A single front-loaded sentence with a category tag, verb, and scoped resource, with zero filler. It is perhaps terse to the point of leaving gaps, but nothing is wasted.

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?

An output schema exists, so return-value explanation is not required, and a zero-param lister is inherently simple. Still missing is the operational context an agent would want: what happens if no workspace is configured, and how this relates to listing or inspecting variants.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. The workspace scoping implied by "configured workspace" is the only free variable and is mentioned.

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 gives a specific verb ("List") and resource ("PRJ filenames") scoped to "the configured workspace", so an agent knows exactly what comes back. It does not explicitly distinguish itself from the nearby pvsyst_list_variants or pvsyst_inspect_project, relying on the reader to infer projects vs. variants.

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?

Usage is only implied: listing projects is obviously a discovery/entry step, and "configured workspace" hints at the prerequisite state. There is no explicit when-to-use, when-not-to-use, or pointer to pvsyst_list_variants or pvsyst_inspect_project as follow-ups.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read, but it does not disclose whether archived variants appear, whether results are paginated or capped, or what identifiers the returned IDs are usable with.

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?

One compact sentence with the category tag front-loaded. Nothing extraneous, though brevity here comes at the cost of missing detail rather than being efficiently dense.

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?

The output schema covers return values, relieving the description of that duty. However, for a tool whose only parameter format is unknown and whose filtering behavior (archived or not, ordering) is unspecified, the description leaves material gaps.

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% and the single required 'project' parameter is undocumented. The description says 'existing project' but doesn't clarify whether the value is a project name, ID, or path — the key ambiguity for correctly invoking this tool.

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 (list) and resource (variant IDs) scoped to an existing project, which an agent can distinguish from pvsyst_list_projects and the various create_variant tools. It could be sharper about whether archived variants are included, but the core action is unambiguous.

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?

No guidance on when to use this versus pvsyst_inspect_project, pvsyst_get_variant_parameters, or pvsyst_list_projects. A reader infers it's the entry point for enumerating a project's variants, but nothing is stated about prerequisites or alternatives.

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

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

With no annotations, the description carries the full burden and does so: it discloses that preview never starts/activates/selects/types, that only a newly launched process receives GUI actions, that a preexisting matching session returns already_open with owned=false and existing_session_read_only=true, that ambiguous/busy sessions are left untouched to preserve unsaved work, and that no INI/clipboard/VC patching or force-termination occurs. It even states a failed cold launch discloses its owned PID/stage for inspection.

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 sentence one, but the body is a semicolon-chained block with jargon like 'Chinese8.1.6rev49278/DPI96' that adds little for an agent. Several clauses (house import, geometry validity, simulation certification disclaimers) could be compressed without losing selection signal.

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 native-GUI mutation tool with no annotations and no output schema, the description covers side effects, session states, error disclosure, and even names returned fields (already_open, owned, existing_session_read_only). Remaining gap is the unspecified 'project' argument format and the exact opened/failed return shapes.

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 coverage is 0%, so the description must compensate and it only partly does: dry_run is explained as the preview/cold-launch switch and confirm as the second gate alongside dry_run=false. The required 'project' parameter is left ambiguous—'the final project basename ... is checked' hints at name vs. path but never clarifies the accepted format.

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 gives a specific verb and resource: open a workspace PRJ via the native GUI, and it is scoped to the 'Projects & Variants' area. It does not name a sibling it is an alternative to (e.g. pvsyst_prepare_design_project or pvsyst_inspect_project), though 'This is not a native dirty-state detector' rules out one misreading.

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?

Usage conditions are explicit: a prerequisite INI DataPath must already equal the MCP workspace, preview never mutates, and a cold launch requires dry_run=false AND confirm=true. What is missing is routing to alternatives—it never says when to use inspect_project or prepare_design_project instead.

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

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 important behavior: 'Preview builds in memory without writes; execution never overwrites or backs up an existing project.' It also warns that unsupported shading, sharing, and common load/storage/transformer systems 'stop' and that inherited weather/losses/electrical suitability 'require review.' That is strong disclosure of side effects and failure modes, though it does not cover permissions, exact return contents, or rate limits.

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 sentence, and most clauses carry real constraints. But the description is a dense wall of semicolon-separated jargon that would be easier to use if split into structured sections for preconditions, side effects, and exclusions. It is appropriately sized for a complex engineering tool but poorly structured.

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, and 0% schema coverage, the description covers behavioral constraints and failure modes reasonably well. It is incomplete for a preparation tool because it never explains what a preview or execution returns, and it leaves several parameter names undefined. An agent could attempt a call but would be guessing about the result shape and identifier formats.

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 only partially does. It explains block semantics ('Each block names a unique source_subarray_id and count INCLUDING the original') and implies dry_run behavior via preview vs. execution. It says nothing about what source_project, source_variant, or new_project strings should contain, leaving most parameters undocumented.

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 a specific verb and resource: 'Prepare one NEW project from explicit counts of fully defined native block types.' It also sets scope by excluding native runs, GUI, INI, weather acquisition, and certification. However, it does not explicitly differentiate itself from close siblings like pvsyst_prepare_design_project or pvsyst_prepare_sourced_design, and jargon such as 'source VC and PRJ' leaves the exact nature of the preparation somewhat opaque.

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 gives constraints on use ('Cover every source subarray exactly once, at most 100 blocks in total', 'Copy whole exclusive inverter/MPPT/string branches'), which imply when the tool applies. But it never names an alternative tool or states the condition that would route an agent to pvsyst_prepare_design_project or pvsyst_create_project instead. Usage guidance is present but only implicit through exclusions and preconditions.

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

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

With no annotations, the description carries the burden well: it discloses that dry_run writes nothing, that execution stops before SFI/CSV/PDF/run, that existing files are not overwritten and templates/assets are protected, that quota exhaustion doesn't block preparation, and the meaning of status/prepared flags. The gaps are around exact return shape and error payloads, which are only sketched.

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 remainder is a dense ten-sentence wall of jargon ('using existing flow gates', 'exact PAN/OND', 'sourced design envelope') that is hard to parse and mixes several distinct concerns (boundaries, idempotency, quota, status flags, file naming) without grouping. Readable but not economical.

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 nested-request tool with no annotations and no output schema, the description covers the important behavioral surface: what it does and doesn't do, safety/protection guarantees, status semantics, result-file naming, and the handoff artifact for downstream tasks. Missing only the concrete return/issue format, which an agent would need to interpret failures fully.

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?

Top-level schema coverage is 0%, so the description must compensate; it does map the spec contents (exact PAN/OND and template, explicit counts or design envelope, declared angles/losses, bound existing/csv/open_meteo weather) and explains dry_run's no-write behavior and report_pages validation. But it gives no per-field syntax or defaults, and much of the nested field meaning is left to the $defs that the coverage metric doesn't credit.

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 names a specific verb+resource ('Prepare one new design project') and explicitly scopes it as without GUI or annual simulation, which separates it from pvsyst_simulate_design by name. It could be sharper against prepare_sourced_design / prepare_block_project, whose boundaries it never mentions, but the core operation is unambiguous.

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 implies when to use it ('prepared_project gives exact project/variant/year/SIT/MET for a subsequent house task or explicit native run') and when not to simulate ('stops BEFORE SFI/CSV/PDF/run'). However, it never explicitly contrasts the three prepare_* siblings or says 'use this instead of X when Y', leaving the routing decision partly inferred.

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

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

No annotations are provided, so the description carries the full burden and does so: dry_run=true writes nothing, the source is preserved, an ASCII Date;P Load / ;kW CSV is written to UserHourlyParams plus an import record to Results, existing names are preserved, and write failure retains partial outputs. Failure semantics are enumerated precisely (missing/duplicate/non-hourly/negative/nonfinite rows stop) along with what is deliberately NOT done (no gap filling, resampling, renormalization, net-meter interpretation, or time shift).

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?

Purpose is front-loaded in the first clause and nearly every sentence adds distinct information. Density is high and some sentences stack multiple constraints, but there is little true filler — the main cost is a slight kitchen-sink feel that makes skimming harder.

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 9-parameter, 0%-schema-coverage, unannotated mutation tool with no output schema, this covers inputs, validation rules, side effects, output locations, failure behavior, and the downstream step required to actually use the produced CSV. An agent has enough to invoke it correctly and to know what it must do next.

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% across 9 parameters, so the description must compensate and largely does: it explains the date column and load column expectations, accepted date formats (iso, pvsyst_dot, pvsyst_slash) with literal examples, the whole-hour UTC offset with no DST, the 8760/8784 interval-start hour basis, and dry_run behavior. The output_name parameter is never explained, which is the main remaining 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?

Opens with a specific verb+resource+scope: 'Inspect or prepare a NEW native hourly load CSV from workspace/UserData.' It then explicitly separates this from native consumption ('ready/prepared concern this CSV only... bind the CSV to a variant') and distinguishes it from the input-param-file DAT channel, so an agent can tell it apart from siblings like create_load_variant or create_native_load_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?

Gives a clear use context (inspect or prepare), the preconditions that must hold, and an explicit exclusion ('input-param-file is an advanced parameters DAT, not a load CSV channel') plus a required follow-up step. It stops short of naming an alternative sibling tool by name, so routing is implied rather than prescribed.

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

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

With no annotations, the description carries the full burden and does well: it discloses that source text is never returned, that the identity label cannot be overridden, that conflicts return blocked with the concrete field, and that no envelope/coefficient/limit can be injected without a citation. It omits permission/auth needs and any rate or size limits, keeping it below a 5.

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 and nearly every clause carries substantive information, but the text is delivered as long run-on sentences with parenthetical asides that are hard to parse on first read. It is dense rather than padded, yet a bulleted or segmented form would convey the same content more reliably.

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 5-parameter nested tool with no annotations and no output schema, the description covers inputs, validation behavior, status semantics, and return contents (electrical_design draft, reused envelope result, citation provenance). Remaining gaps are minor: no ordering relative to sibling preparation tools and no detail on individual design-goal fields.

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 does: pan_name/ond_name are exact loose component filenames resolved workspace-first, sources maps short ids to declared text of kind manufacturer/site/assumption, and each declaration ties a value to a source id, excerpt, and exact value/unit tokens. The nested design goals are only labeled 'explicit engineering goals', leaving individual goal fields undescribed.

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 compound action: bind caller-declared excerpts to source text and build the design-envelope request, plus the identity composition rule. It is clear what the tool does, but it never names or contrasts the obvious siblings (pvsyst_prepare_design_project, pvsyst_simulate_design, pvsyst_build_sourced_component), so differentiation is left to inference.

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?

Usage is implied through the status outcomes (ready/needs_review/blocked) and the rejection conditions (identity disagreement, repeated field, legacy binary/non-UTF-8), which tells an agent when the call will succeed. However, there is no explicit when-to-use versus pvsyst_prepare_design_project or pvsyst_build_sourced_component, and no stated prerequisites or ordering.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: dry_run writes nothing, raw bytes are preserved, only columns/units are normalized, monthly CSV/MEF are created, warnings become needs_review, existing outputs are never overwritten, and failure artifacts are retained. It also correctly cautions that a prepared file is not native MET certification.

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 description is dense but front-loaded with purpose and required constraints, then behavior and downstream usage. Almost every clause adds operational value, though the long semicolon-heavy structure makes it harder to scan than it could be.

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 orchestration tool with no output schema and no annotations, the description does well on behavior and constraints. However, it does not fully document the seven inputs or the returned artifact structure, and the requiredness mismatch with the schema leaves an invocation ambiguity.

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 coverage is 0%, so the description must explain seven parameters. It adds useful meaning for country_code, time_basis, and dry_run, but leaves year, csv_name, met_name, and sit_name largely unexplained, and its statement that country_code/time_basis are required conflicts with the schema showing zero required parameters and empty-string defaults.

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 starts with a specific verb and resource: preparing NEW native SIT/MET plus a provenance manifest from one hourly CSV. It clearly scopes the operation to GHI/DHI/Tamb and distinguishes it from lower-level weather tools by describing the orchestration of create-site and convert-meteo.

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?

Usage is implied by the scope: preparing new native weather files from a CSV, not inspecting, acquiring, or reviewing one. It also names a downstream handoff to simulate_template, but it does not explicitly compare this tool against siblings such as inspect_weather_csv, acquire_weather, build_monthly_weather, or review_weather.

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

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

With no annotations, the description carries the full behavioral burden. It discloses one caveat ('Unresolved loose files may still exist inside the encrypted built-in database'), but does not explicitly state that the operation is read-only, what permissions are needed, or what the response looks like.

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?

Two short sentences with the inspection purpose front-loaded and the caveat second. There is little waste, though the bracketed '[Components]' tag adds no meaning.

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 read/inspect tool with two required undocumented parameters and no output schema, the description should clarify the return shape (e.g., resolved vs unresolved references) and the meaning of the inputs. It provides only a cryptic database caveat, leaving the agent unsure what calling it actually yields.

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 explain the required 'project' and 'variant' parameters. It does not say whether these are names, file paths, or IDs. The mention of 'PRJ/VC references' only weakly implies they identify project and variant files.

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 names a verb ('Inspect') and a resource (PRJ/VC references to PAN, OND, BTR, GEN), which is specific to a domain expert but opaque to an agent that doesn't know these acronyms. It does not distinguish this tool from close siblings like pvsyst_get_variant_components, pvsyst_inspect_project, or pvsyst_list_components.

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 guidance on when to use this tool versus alternatives. The sibling set contains several overlapping inspection/component tools, and the description never names one as an alternative or states a selection condition.

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

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

With no annotations, the description carries the full burden and does well: it explicitly states readonly behavior, excludes GUI, license query, simulation, repairs, and writes, and clarifies that ready/needs_review only describe the handoff while native_consumption_verified remains false. It still does not describe failure behavior or rate limits, so it is strong but not exhaustive.

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 description is compact, front-loads the read scope, and avoids filler. It is dense and somewhat run-on, especially the parenthetical engineering clauses, but every sentence contributes meaning.

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?

The description conveys the conceptual handoff contents and readonly constraints, which is useful given no output schema. However, it does not fill the parameter documentation gap or explain the response shape, and it lacks explicit routing against similar project/variant inspection tools, leaving material gaps for correct invocation.

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 for all three parameters. It only gestures at the declarations parameter via 'explicit caller declarations' and provides no meaning, format, or expected values for project, variant, or declarations. This leaves the agent largely dependent on naming alone.

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 names a specific read operation and enumerates the saved engineering data it returns: equipment, counts, orientation/circuit relationships, input dependencies, declarations, inherited values, missing inputs, and review items. It is clear what the tool does, but it does not explicitly distinguish it from nearby siblings such as pvsyst_review_project_inputs or pvsyst_inspect_project.

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?

Usage is implied by the engineering handoff framing and the readonly constraints, but there is no explicit statement of when to use this tool instead of pvsyst_review_project_inputs, pvsyst_inspect_project, or pvsyst_get_variant_parameters. The agent must infer the intended handoff scenario.

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

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

With no annotations, the description carries the full behavioral burden. It implies a read of a CSV file but does not say whether it is read-only, what happens if summary_name is missing or invalid, how columns affect output, or what shape the returned values take.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.