cura_operation

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

Annotations already declare a destructive, non-readOnly, closed-world write, so the safety profile is covered. The description adds genuinely new behavior: project saves are asynchronous and return an operation_id that must be polled, and the tool intentionally never triggers a print or upload. It doesn't spell out what a set_settings or slice does to existing output, but the added async and no-side-effect context is real value beyond annotations.

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?

Three short sentences, front-loaded with the action list, then the async save caveat followed by poll routing, then the safety boundary. No filler or restatement of the name.

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?

Given 10 parameters, nested values object, 40% schema coverage, no output schema, and a destructive annotation, the description covers the dispatch and save lifecycle but omits the confirmation_token origin, what values must contain, and how mode/file_name/folder interact. It is adequate but leaves an agent guessing on the multi-step save path.

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 only 40% across 10 parameters, so the description bears extra burden and only partially meets it: the four action verbs disambiguate the action enum (which has no per-value schema descriptions), which is the key dispatch parameter. It says nothing about values, extruder, build_plate, file_path, or that confirmation_token comes from the confirmation siblings, leaving several parameters unexplained in both places.

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 specific verbs and resources (apply settings, slice, export G-code, save 3MF project) that map one-to-one onto the four action enum values, so the agent knows exactly what the tool does. It also distinguishes itself from siblings by declaring it never prints or uploads automatically, ruling out start_print/upload_gcode confusion.

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?

Gives clear usage context: 'Apply approved' ties this to the confirmation flow, and the save branch explicitly routes the agent to cura_project_save_status for polling. It also names a when-not condition ('never prints or uploads automatically'). It stops short of saying when to prefer cura_settings or create_cura_confirmation first, so it isn't a full 5.

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