Skip to main content
Glama

Delete item

delete_item
Destructive

Permanently delete one item; every deletion an agent can make goes through this tool, and none can be undone. item secret: one key and its whole version history from one environment (to change a value use manage_secrets). item field: one project key/value field (fields keep no history). item login: one saved login by id or exact name. item file: one secure file or attachment by id or exact name (a name several files share needs the id). item environment: an empty environment and its deployment URLs; refused while it holds any secret or file or is synced to Vercel, a project keeps at least one environment, and it needs the owner role. item deployment_url: forget one recorded URL by url_id (nothing is taken offline; if it was primary the oldest remaining becomes primary). Protected and sealed items, sensitive fields and files in protected projects, and archived projects are refused. One client approval of this tool covers every item kind. Audited. Requires the write scope of the item (secrets:write, projects:write, logins:write or files:write; a sensitive field also secrets:write) and the editor role, owner for environments.

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": {
      "item": "<item>",
      "project": "<project>"
    },
    "name": "delete_item"
  }
}

Input Schema

NameRequiredDescriptionDefault
keyNosecret: the key. field: the field name, as get_project lists it
fileNofile only: file id, or its exact name when unique
itemYesWhat to delete
loginNologin only: login id, or its exact name
url_idNodeployment_url only: deployment URL id, from list_project_items item deployment_urls
projectYesProject slug or id
environmentNosecret, environment: required

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.5/5.0
Behavior5/5

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

Despite annotations already declaring destructiveHint and non-idempotency, the description adds substantial behavioral context: irreversibility, per-item-kind side effects (deployment_url leaves nothing offline and promotes the oldest remaining URL to primary; environment deletion is refused while it holds secrets/files or is Vercel-synced; a project retains at least one environment), refusal cases for protected/sealed items and archived projects, a single client approval covering all item kinds, audit logging, and the exact write scopes and roles required.

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

Conciseness4/5

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

Front-loaded with the core action and irreversibility, then organized kind-by-kind, which suits a polymorphic delete. It is dense and semicolon-chained, so it reads as a wall of text, but nearly every clause carries unique operational information.

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

Completeness4/5

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

For a destructive, seven-parameter tool with no output schema, the description covers irreversibility, authorization, approval, refusals, and per-kind effects. The one gap is what a successful call returns (a confirmation object, remaining item list, nothing), which matters since no output schema exists to answer that.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by mapping parameters to item kinds (key for secret/field, login by id or exact name, file by id or exact name, url_id for deployment_url, environment for secret/environment) and adds the disambiguation rule that a name shared by several files requires the id. This adds real meaning beyond the schema's own 'file only'/'deployment_url only' notes.

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 and resource ('Permanently delete one item') and then enumerates each of the six item kinds the tool acts on, so the agent knows exactly what scope of deletion this covers. It also distinguishes the tool from the sibling that handles value changes ('to change a value use manage_secrets').

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

Usage Guidelines4/5

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

The description explicitly scopes usage ('every deletion an agent can make goes through this tool, and none can be undone') and routes updates elsewhere via manage_secrets. It also lists the runtime conditions under which the call is refused, which effectively defines when-not to use it. It doesn't address related alternatives such as archiving a project instead of deleting items, so it stops short of full coverage.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources