add_layer_action

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

With no annotations, the description carries the full behavioral burden. It does disclose two valuable traits: the action fires before the target layer prints, and z is snapped to the nearest real layer at or above the requested height. It does not say whether the action persists in the saved project, how it interacts with existing actions at the same height, or what errors occur for out-of-range z or plate.

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 trigger condition before the action enumeration, and every clause adds information rather than repeating the name. The nested parentheticals make it dense but not padded; a slightly cleaner enumeration of action→parameter coupling would tighten it further.

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 mutation tool with no annotations and no output schema, the description covers the trigger semantics and most parameters but leaves the required `plate` argument unexplained and says nothing about persistence, error conditions, or the return result. Adequate to call correctly in the happy path, incomplete for anything adjacent.

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, and it largely does: z gets a unit and a snapping rule, action gets its three legal values with meanings, message is explained as shown in Bambu Studio, filament is explained as the AMS slot used from that height on, and gcode accepts full command lines. The notable omission is `plate`, which is required but never mentioned, and the coupling between action and the other params is only implied.

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?

Specific verb+resource with scope: it registers an action that fires when the print reaches height z, before that layer prints. The three action modes (pause, filament_change, gcode) are enumerated, so the agent knows exactly what class of operation this is and can distinguish it from siblings like set_height_range or remove_layer_action.

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?

Each action value carries an inline use case — pause to insert magnets or nuts, filament_change to switch AMS slots from that height, gcode for arbitrary commands like 'M104 S210'. That is clear when-to-use-per-mode context, but there is no explicit statement of prerequisites (a loaded project, a valid plate) or of when to prefer remove_layer_action / set_height_range instead.

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