pvsyst_review_engineering_brief

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 well: it declares readonly status, enumerates absent capabilities (no files, PDF, executable, license, network, GUI, INI), and discloses that only blocked or needs_review results are returned and that facts are never certified. This is strong side-effect and result-contract disclosure; only idempotency/rate behavior is left unstated.

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 each subsequent sentence adds substantive constraint (checks performed, unit/citation rules, access limits, return contract). It is dense and multi-clause but justified by the tool's complexity, with little 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 complex, annotation-free, output-schema-less review tool, the definition covers the essential ground: what it checks, unit/citation conventions, access constraints, and that it returns only blocked/needs_review without certifying readiness. What remains thin is the precise meaning/schema of the blocked vs needs_review outcomes, but overall it is sufficient to call 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%, but the schema itself is structurally rich (enums for field, unit/scope/pdf_page definitions). The description adds meaning beyond it: it mandates explicit count/W/kW/kWh/V/A/deg/m units and physical PDF page citations, and clarifies that no automatic unit conversion or inference is done — guidance a caller needs to populate the brief correctly.

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 (Review) and resource (caller-structured cited engineering facts) and scopes it clearly with 'before a native project exists,' which distinguishes it from post-project review siblings like pvsyst_review_project_inputs. The named checks (same-scope conflicts, DC/AC arithmetic, Pmax vs Vmp*Imp, missing PAN/OND/weather) make the intended job 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?

The phrase 'before a native project exists' gives a real timing/context cue for when to reach for this tool. However, it never names an alternative (e.g., pvsyst_review_project_inputs) or states an explicit when-not-to-use condition, so the agent must infer selection among the many review/validation siblings.

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