clm_shipment_command_delete_draft_shipment

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

The destructiveHint=true annotation correctly signals that this is destructive, and the description does not contradict that annotation. However, the description's claimed behavior (status transition, grouping counts, background processing) appears unrelated to deleting a draft shipment, so it does not transparently disclose the actual destructive behavior. The annotation carries the only reliable safety signal.

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?

The description is a single sentence and reasonably compact, but most of its content is irrelevant to a delete-draft-shipment operation. The long parenthetical list of statuses and background-processing details adds noise and does not earn its place. A correct short description would be more concise and more useful.

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?

The description omits the core delete behavior, prerequisites such as the shipment needing to be a draft, and any caution about the destructive nature beyond the annotation. The output schema does not compensate for the mismatch. This is seriously incomplete for a destructive command with one required parameter.

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%, and the description says nothing about the ShipmentId parameter or how it should be provided. The parameter name is self-explanatory to a degree, but the description does not clarify that it identifies the draft shipment to delete or whether null is acceptable. With 0% schema coverage, the description needed to compensate and did not.

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 says the tool 'Transitions a shipment to a new status' and lists statuses, which is a status-update behavior, not a delete-draft-shipment behavior as the tool name states. It never mentions deleting, discarding, or removing a draft shipment, so it is misleading about the core purpose. It also fails to distinguish this from the sibling clm_shipment_command_update_shipment_status.

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 provides no guidance on when to use this tool vs alternatives. It does not state that this is for deleting a draft shipment, nor does it explain when another command like discard_shipment or update_shipment_status should be used instead. The status-transition language actively suggests using it for a purpose likely handled by a sibling tool.

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