clm_shipment_command_save_shipment_wizard_timeslots

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds valuable behavior beyond that: it discloses that zone selection triggers resolution of a waiting area, and — most importantly — that edits to submitted shipments are not applied directly but queued as a pending draft. This state-dependent side-effect disclosure is exactly the kind of context annotations do not carry.

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?

A single dense sentence that front-loads the core purpose ('Saves the timeslot step') before elaborating the two behavioral branches. Every clause adds information and there is no filler, though the sentence is somewhat long and run-on with nested clauses.

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 the tool's moderate complexity (9 parameters, 0% schema coverage, branching behavior), the description covers the essential flow and the critical state-dependent draft behavior, while an output schema exists to offload return-value documentation. Remaining gaps are the exact roles of Slots and BookingDate, which are partially inferable from context.

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. It does map several parameters to concepts: Zone and WaitingArea are linked, the schedule window maps to ScheduleStart/EndDateTime, and equipment reservations map to Bookable/NonBookableEquipments. However, Slots and BookingDate semantics remain unexplained, and the distinction between bookable and non-bookable equipment is not clarified, so compensation is partial.

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 a specific verb+resource ('Saves the timeslot step of the shipment wizard') and explains what that step actually involves: zone resolution, schedule window, equipment reservations, and the draft path. This clearly distinguishes it from sibling wizard-save tools (booking_dates, material, other_info, unloadings) and the smart_shipment variant without needing to open the schema.

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 gives clear context for when each behavior applies: a shipment still being created applies changes directly, while an already-submitted shipment being edited stores a pending draft. It does not explicitly name alternatives or exclusions, but the 'timeslot step' scoping makes the selection context apparent among the wizard-save siblings.

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