pcm_import_bulk_parameters

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

With no annotations provided, the description carries the full behavioral burden. It explicitly flags that this MODIFIES PROTECTION SETTINGS (a write/mutation warning), reveals preprocessing behavior (snapshots first), and discloses the wider blast radius and lack of pre-flight validation. This is strong disclosure. It doesn't detail error handling or rollback behavior, but for a bulk import tool this disclosure is quite thorough.

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-loaded with the critical safety warning (MODIFIES PROTECTION SETTINGS), and every sentence earns its place: the purpose, the requirements, the preprocessing note, and the risk guidance with a named alternative. No wasted words, 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?

This is a high-stakes mutation tool with no annotations, no parent description coverage of parameters, but with an output schema present. The description covers purpose, safety requirements, behavioral risks, and alternative recommendations. The main gap is parameter semantics for project and param_dir, but given the safety focus and existing output schema, the description is quite complete for guiding safe 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. The description tacitly implies `confirm` is required (via 'requires... confirm=true') and `param_dir` relates to the bulk parameter files. However, it never explicitly describes what each parameter means or the format expected for `param_dir` (directory path, glob pattern, etc.). The confirm parameter semantics are partially covered, but project and param_dir semantics remain unclear.

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 the tool imports `.xrio` parameter files for many IEDs at once, with a specific verb (import), resource (`.xrio` files), and scope (bulk/many IEDs). It explicitly distinguishes from the sibling `pcm_import_parameters` by noting the wider blast radius and lack of per-file pre-flight validation, contrasting with the single-IED 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?

The description provides explicit guidance: it states the write requirement (PCM_MCP_ALLOW_WRITES=1 and confirm=true), warns about the wider blast radius, explicitly notes the absence of per-file pre-flight validation in bulk form, and directly recommends preferring `pcm_import_parameters` per IED when the change matters. This is outstanding when-to-use vs when-not-to guidance with a clear named alternative.

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