set_property

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description does not need to belabor mutability. It adds valuable insight beyond annotations by warning that setting Identification renames the object, which invalidates the path for subsequent calls. This goes beyond what the structured metadata conveys.

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 primary action, and each subsequent sentence adds essential caveat detail. No filler words or redundant content. It reads cleanly and efficiently.

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 setter tool with two parameters, relevant annotations, and an output schema, the description covers the key semantic differences versus siblings and the main usage pitfall. It could improve by explicitly noting that only scalar values are accepted or by giving a minimal example path, but the existing warning about renaming and materials meets most contextual needs.

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?

The schema refers to path and value, with value already described as a scalar and reference guidance. The description adds that path is a dotted path and that material references are not valid via this tool, which partially compensates for the path property's missing schema description. However, it does not fully specify path structuring or property naming conventions, leaving some ambiguity.

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 states the tool sets a writable PLAXIS property via a dotted path. It explicitly distinguishes itself from the assign_material sibling, calling out the material reference scenario and directing users to the 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 clear when-not-to-use guidance for material references, explicitly naming assign_material as the correct alternative. It also flags the path-changing consequence of setting Identification, giving the user a critical context for avoiding future errors.

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