Skip to main content
Glama

Manage files

manage_files
Destructive

Upload or delete an encrypted file, such as a service-account JSON or a TLS key, in a project or one of its environments. A single setting belongs in manage_secrets. To read a file use reveal_values item file; to list files use list_project_items item files. Actions (arguments besides action and project):

  • upload (name, content; optional encoding, environment, content_type): up to 1 MB once decoded. Send text as is; for a binary file send base64 with encoding "base64", or the base64 text itself is stored. Without environment it belongs to the whole project. Uploading a name that exists adds a second file; delete the older one by id.

  • delete (file): removes one file (secure file or attachment) permanently, by id or by an exact name no other file shares. Errors are messages: a protected or archived project, invalid base64, a file over 1 MB, a name that matches nothing or several files. Audited. Needs files:write, the editor role and full access to the project.

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": {
      "action": "<action>",
      "project": "<project>"
    },
    "name": "manage_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
fileNodelete only: file id, or its exact name as list_project_items item files shows it
nameNoupload only: file name as it will be listed, e.g. service-account.json
actionYesWhat to do
contentNoupload only: the file's contents, plain text, or base64 when encoding is base64
projectYesProject slug from list_projects, e.g. my-app, or its id (a UUID)
encodingNoupload only: how content is written, utf-8 text (default) or base64 for binary files
environmentNoupload only: the environment the file belongs to (default: the whole project)
content_typeNoupload only: MIME type, e.g. application/json (default: application/octet-stream)

Output Schema

NameRequiredDescriptionDefault
idNoupload, delete: the file id
nameNoupload, delete: the file's name
sizeNoupload: the size in bytes
deletedNodelete: true once the file is gone
environmentNoupload: the environment's slug, null for the whole project

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": {},
      +  "properties": {
      +    "deleted": {
      +      "description": "delete: true once the file is gone",
      +      "type": "boolean"
      +    },
      +    "environment": {
      +      "description": "upload: the environment's slug, null for the whole project",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "id": {
      +      "description": "upload, delete: the file id",
      +      "type": "string"
      +    },
      +    "name": {
      +      "description": "upload, delete: the file's name",
      +      "type": "string"
      +    },
      +    "size": {
      +      "description": "upload: the size in bytes",
      +      "type": "number"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Added

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only flag destructive/not-read-only/not-idempotent; the description adds the operational facts an agent actually needs: a 1 MB decoded cap, that uploading a duplicate name creates a second file rather than overwriting, that delete is permanent, the enumerated error conditions, audit logging, and the required scope plus role (files:write, editor, full project access). That is substantial value beyond the structured hints and consistent with them.

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 purpose, then a routing sentence, then a per-action bullet list, then errors and permissions. Dense but every line carries decision-relevant information; nothing is filler.

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?

For an 8-parameter, dual-action, destructive tool this covers purpose, per-action argument mapping, limits, collision behavior, error surface, and authorization. An output schema exists, so the description correctly omits return-value detail.

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: the size limit is expressed as 1 MB 'once decoded' rather than the raw maxLength, binary handling and the encoding='base64' contract are explained, defaults for environment and content_type are restated in context, and delete's id-or-unique-exact-name rule is clarified. The non-obvious case that re-uploading a name does not replace the existing file is exactly the kind of semantics the schema cannot express.

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 specific verbs (upload, delete), the exact resource (an encrypted file such as a service-account JSON or TLS key), and the scope (a project or one of its environments). It immediately separates itself from manage_secrets ('a single setting belongs in manage_secrets') and from the read/list siblings reveal_values and list_project_items.

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 routes the agent: settings go to manage_secrets, reading to reveal_values item file, listing to list_project_items item files, and everything else here. Within the tool it also splits guidance per action (upload vs delete) so the agent knows which argument set applies.

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