make_retraction_test

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

With no annotations, the description carries the full burden and does disclose a key non-obvious behavior: multiple separate projects are created because Bambu printers cannot change retraction mid-print, and the outputs must be printed sequentially. It also names the follow-up mutation path. It omits whether existing projects are affected, whether projects are saved/opened, and what the call returns.

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 dense sentences, front-loaded with the purpose and followed by the workflow and the exact follow-up calls. The parenthetical justification earns its place because it explains the multi-project design. Minor slack in the run-on structure of the last 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?

For a 2-parameter, annotation-free tool with no output schema, the description covers the purpose and the post-test action but not the call's own outcome: how many projects/plates are created, whether they are named, whether they are saved or opened, and what the caller gets back. An agent would still need to guess at the side effects before invoking it.

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. It implies the `lengths` array ('one project per retraction length') and hints that `filament` is the slot ('for a filament slot'), but never states units, ordering, or what happens when `lengths` is null (the default), leaving the most important defaulting behavior undocumented.

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 names a specific verb+resource: it generates a stringing/retraction test with one small project per retraction length for a filament slot. That is clearly distinguishable from the sibling test generators (make_temperature_tower, make_flow_test, make_pa_tower, make_vfa_test). It stops short of explicitly contrasting itself with those siblings, but the purpose is unambiguous.

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 gives a concrete workflow: print the tests one after another, pick the shortest length with no strings between the two pillars, then apply it via set_setting('filament_retraction_length', value, slot) or save_filament_preset. That is strong when-and-how guidance. It does not state prerequisites (e.g. a printer/AMS/filament must be selected) or when to prefer another test tool instead.

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