tc_delete_item

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral detail: no undo via API, Trimble Connect's soft-delete nuance, admin web-UI restore, the force flag's background deletion of the whole subtree, and the confirmation safety gate. This is far beyond the structured 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?

The description front-loads the most critical information (destructive, no undo), then details prerequisites, parameter semantics, and the return value. Every sentence earns its place—no filler—and the structured 'Args' section makes it scannable.

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?

This is a destructive operation with several caveats: irreversibility, confirmation requirements, environment variable gate, force semantics, and background jobs. The description covers all of these, and an output schema is available for return-value details. It is complete for a high-risk tool.

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%, but the description compensates fully by explaining all five parameters: project_id, item_id, confirm as a safety gate, item_type defaulting to FOLDER versus FILE, and force required for non-empty folder subtree deletion. It also notes the return shape, giving agents the semantic context missing from the schema.

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 object—'Delete a folder or a file'—clearly identifying the tool's operation. It distinguishes itself from sibling tools like tc_create_folder, tc_move_item, and tc_rename_item by explicitly naming the deletion scope.

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 explicit operational conditions: TC_ENABLE_WRITE=1, confirm=true, and the need to always show the user what will be deleted. It explains when force is required. It does not explicitly name alternative tools or state when not to use the tool, but the safety and prerequisite guidance strongly imply the intended usage context.

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