Delete rows of element files from the engine. The file stays on the server disk; no undo, so confirm before removing.
Delete rows of element files. The file itself stays on the server disk - there is no delete for it anywhere in the product; the owner reclaims space by running the idle-files audit module. No undo on the row: warn first.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes |
Changes observed during successful MCP inspections.
v6.5.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so admirably. It discloses the non-obvious behavior that the physical file remains on disk, that there is no undo, and that space is reclaimed via the idle-files audit module. This is exactly the kind of behavioral transparency needed for a destructive operation.
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?
Three concise sentences, each adding critical information: the action, the file persistence behavior, and the no-undo warning. No redundancy, and the most important warning is front-loaded. Perfectly structured for quick consumption.
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 behavioral aspects are well covered, but the parameter structure is unexplained. An agent invoking this tool would know the purpose and consequences but not how to construct the 'files' array correctly. Since the tool is simple (one parameter) and has no output schema, the description could have included a brief note on the required fields. This gap reduces completeness.
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 for explaining parameters, but it does not. The schema shows a 'files' array with objects containing 'entity' and 'id', yet the description never explains what these fields mean or how to specify which rows to delete. The agent is left without guidance on how to populate the required parameter.
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 explicitly states the action 'Delete rows of element files' and clarifies it is not deleting the physical file. This clearly distinguishes it from sibling remove tools like engine_files_remove vs engine_static_remove, and the wording is specific to the file row context.
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 clear usage context: it warns about no undo and advises to warn first, implying when to use it (when you intend to remove file references). It also indirectly explains that for deleting actual files, the idle-files audit module is used, so it guides the agent toward the correct alternative for file deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.