pcm_import_scd

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

No annotations provided, so the description carries full burden — and it does exceptionally. It discloses the mutation side effect, the snapshot/verification behavior, the silent IED-loss failure mode inherent to PCM600's import, and the destructive nature of the two overwrite parameters. This is unusually rich behavioral disclosure for a tool with zero annotation coverage.

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 tightly structured: opens with the purpose, then leads with the most critical safety fact (MODIFIES THE PROJECT), then the verification mechanism, the failure mode, and the overwrite flags. Every sentence earns its place and information is front-loaded by importance, not buried.

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 an output schema exists (so return values need no explanation) and zero annotations, the description fully covers the tool's complexity: prerequisites, verification behavior, failure modes, and destructive-parameter warnings. This is an unusually complete description for a mutation tool handling critical project data.

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 confirm (safety gate), ln_overwrite_allowed and smt_overwrite_allowed (discard engineering work when true), and clarifies their defaults. The project and scd_path parameters are self-evident from names. Nearly all parameter semantics are conveyed beyond the bare schema.

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 the action clearly ('Import an SCD file into a PCM600 project') with the resource (PCM600 project) and input (SCD file). The description distinguishes it from sibling read-only tools like scl_list_ieds and pcm_export_scd by emphasizing it MODIFIES THE PROJECT, differentiating it from the export/read operations in the sibling list.

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?

Provides explicit prerequisites (PCM_MCP_ALLOW_WRITES=1 and confirm=true), warns to check apcmp_summary or pcm_cli_info connectivity packages first, and explains when the overwrite parameters should be used. Naming specific alternative tools (apcmp_summary, pcm_cli_info) gives clear when-to-use guidance relative to siblings.

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