Plecs Model Clone

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

Annotations only declare destructiveHint=true; the description adds real context by disclosing that the copy is followed by a load (side effect on session state) and that replacements are regex-based rewrites. However, it never states what happens when the target already exists, how the overwrite flag changes behavior, or when validation failure aborts.

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 paragraphs: the operation and its sequence come first, then the only non-obvious parameter format. Nothing is redundant and the alternative is stated in one clause.

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 values need no explanation, and the core workflow is conveyed. Still, for a destructive 6-parameter tool, the absence of any statement about overwrite collision behavior and validation failure handling leaves a meaningful 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 carries the full burden, yet it only documents the replacements shape and hints at rename and validate. The four remaining parameters - source, target, overwrite, and name's exact effect - are left to name-guessing, and destructive semantics of overwrite are 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 opens with a concrete verb+resource ('Copy a model file') and adds the two behavioral modifiers (optional rename/regex rewrite, load-to-verify). It also explicitly positions itself against schematic editing, so an agent can distinguish it from plecs_model_edit without opening either 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?

The clause 'file-level alternative to schematic editing (PLECS RPC cannot edit a model)' gives a clear selection rationale versus the edit sibling. There is no explicit when-not guidance beyond that (e.g., when to prefer plecs_model_edit or plecs_compare), 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.