Skip to main content
Glama

Delete path

delete_path
DestructiveIdempotent

Deletes a file or directory from the workspace, requiring recursive mode for folders; verify uncertain targets first because deletion is permanent.

Instructions

Delete a file or directory (recursive=true is required for directories). Not undoable. Use when: you remove files or folders. Take a snapshot first when they are not in git. Avoid when: the target is uncertain (check with get_file_info or list_files). Output: entries_deleted, bytes_deleted. Missing path gives not_found.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "relative_path": "<relative_path>"
    },
    "name": "delete_path"
  }
}

Input Schema

NameRequiredDescriptionDefault
reasonNoOptional why (max 400 chars), audit-logged.
recursiveNotrue = delete a directory recursively (required for directories); snapshot it first.
relative_pathYesExact workspace path to delete.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv4.5.0
    • removedInput schema / properties / recursive / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • changedInput schema / properties / recursive / description
      Previous value: -"1 = delete a directory recursively (required for directories); snapshot it first."New value: +"true = delete a directory recursively (required for directories); snapshot it first."
    • removedInput schema / properties / recursive / maximum
      Removed value: -1
    • removedInput schema / properties / recursive / minimum
      Removed value: -0
    • changedInput schema / properties / recursive / type
      Previous value: -"integer"New value: +"boolean"
  2. Addedv4.0.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description still adds real value beyond them: 'Not undoable', a snapshot recommendation for non-git targets, and the not_found behavior for missing paths. It does not discuss permissions or concurrent-deletion effects, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and the irreversible warning, then broken into Use/Avoid/Output lines with no filler. Every sentence carries actionable information, including the return fields that substitute for a missing output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description supplies return values (entries_deleted, bytes_deleted) and the not_found edge case, and it covers the directory-recursion requirement. For a 3-parameter destructive tool with full annotations, nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (relative_path, recursive, reason) are already documented in the schema. The description restates the recursive/directory rule but adds no syntax, path-format, or reason-logging detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (delete) and resource (file or directory) plus the key precondition that recursive=true is required for directories. This clearly separates it from siblings like move_path, copy_path, and apply_patch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly gives both directions: 'Use when: you remove files or folders' and 'Avoid when: the target is uncertain (check with get_file_info or list_files)'. It also names snapshot as a recommended prior step, so an agent has a complete routing decision.

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