project_target_settings_write

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

With no annotations, the description carries real weight: it discloses that output goes to a new 3MF, that geometry, identity and cached G-code references are protected, and that reslicing is required. It stops short of describing overwrite behavior, atomicity, or what expected_source_sha256 guards against.

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?

Front-loaded with the core action and scoping, with the protective caveats following. The telegraphic fragments are efficient, though 'target is object or plate' reads awkwardly as a standalone sentence.

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?

Output schema exists so return values need no explanation, but for an eight-parameter mutation with zero annotation and zero schema-description coverage, missing guidance on overwrite semantics, the concurrency hash, and remove/part_id semantics leaves the definition incomplete.

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 partially does: source/destination as the new 3MF, target as object or plate, target_id as stored IDs, changes as Orca serialized strings. It leaves remove, part_id and especially expected_source_sha256 (clearly an optimistic-lock hash) unexplained, so the gap is only half closed.

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 a specific verb and resource: set object/part or plate print settings into a new 3MF using stored IDs. The 'target is object or plate' clause and 'new 3MF' scoping distinguish it from project_settings_write and settings_write without naming them explicitly.

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?

It clarifies that target is either object or plate and that reslicing is required afterwards, which implies when the tool applies. However, it never states when to prefer this over project_settings_write or settings_write, nor any prerequisites such as whether the destination must be absent.

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