clm_material_handover_command_complete_material_handover

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

Even though annotations already flag destructiveHint=true and idempotentHint=false, the description adds substantial behavioral context not visible anywhere else: the appended completion event, the parent-shipment status aggregation with conditional PDF regeneration, the background thumbnail job, and the time computation from paired events. Nothing in the description contradicts the destructive annotation.

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 main action is front-loaded and every clause contributes distinct information, so there is no waste. However, the entire description is one dense run-on sentence packing six side effects into comma-separated clauses; splitting it into a purpose statement plus a side-effect list would improve scannability without adding length.

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 thoroughly covers the tool's side effects, and since an output schema exists it need not explain return values. However, it assumes domain knowledge such as 'paired handover events' and completion-type semantics, and it does not state preconditions or what happens if the handover is already completed, which matters for a non-idempotent destructive command.

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, but it only gives meaning to the photos and note parameters. ItemId, CompletionType (a bare integer with no enum or hinted meaning), and CompletedByUserId are never explained, and the QR-code responsible-person clause does not clearly map to any schema property. For an agent, the majority of parameters remain ambiguous.

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 opens with a specific verb and outcome ('Marks a handover as Completed') and enumerates concrete effects: appending a completion event, storing photos/note, computing total time, updating the parent shipment, triggering PDF regeneration, and queuing thumbnail generation. This makes the tool's role unmistakable and clearly distinguishes it from siblings like change_material_handover_status or create_material_handover.

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 implies when to use the tool (finalizing a handover with photos, note, and time computation) but never explicitly states it, and it does not route the agent away from the closely related sibling clm_material_handover_command_change_material_handover_status. Preconditions such as the handover's required current status or whether the handover can be re-completed are also absent, leaving the agent to infer selection criteria from the behavior list alone.

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