pvsyst_open_native_project

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.