Skip to main content
Glama

inspect_modal_secret

Lists the variable key names inside a Modal secret by mounting it in a short-lived container and probes the environment without exposing values. Incurs a small compute cost.

Instructions

List the KEY NAMES inside a Modal secret — never the values.

Modal exposes no API for this: neither the CLI, the SDK, nor the gRPC layer can read
a secret's contents, by design. The only way to see which keys a secret defines is to
mount it in a container and look at the environment variable names. So this tool
starts a short-lived container (`modal shell --secret ...`), prints the variable NAMES
only, and subtracts the ones the image and the Modal runtime would have set anyway.

That means, unlike every other read in this server, a call here **starts remote
compute and costs a few cents** (and takes tens of seconds — longer on the first run
for a given image, which has to be built). It is not a free lookup: use
list_modal_resources(resource="secrets") to see which secrets exist, and reach for
this only when you need to know what is inside one.

Values never leave the container: the probe is `compgen -e`, a bash builtin that
prints exported variable NAMES only, so no value is ever printed or read.

Args:
    secret_name: Name of the secret, from list_modal_resources(resource="secrets").
    env: Modal environment the secret lives in.
    image: Optional container image. Omit it to use Modal's default image, which is
        built to match this server's Python — that is the most reliable choice. Pass one
        (e.g. "python:3.12-slim") if the workspace's image builder rejects that Python.
    timeout_seconds: Max seconds to wait, including image build. Default 300.
    profile: Modal profile for this call only. Defaults to the active profile.

Returns: {keys: [...names...], all_env_names: [...], filtered_out: n}. `all_env_names`
    is the unfiltered list, so a key that looks like a runtime variable (e.g. one
    literally named "PATH") is still visible rather than silently dropped.

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": {
      "secret_name": "<secret_name>"
    },
    "name": "inspect_modal_secret"
  }
}

Input Schema

NameRequiredDescriptionDefault
envNo
imageNo
profileNo
secret_nameYes
timeout_secondsNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.0.1
    • addedInput schema / properties / profile
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Profile"
      +}
  2. Addedv0.2.2

TDQS

A4.9/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing that the call starts remote compute, costs a few cents, and takes tens of seconds (longer on first run due to image build) — consistent with readOnlyHint=false and idempotentHint=false. It also explains the underlying mechanism (modal shell + compgen -e) and why values can never leak, plus the filtering of runtime-set variables and the all_env_names escape hatch.

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 payload (key names only) and the cost warning before the mechanics. The explanation of why no API exists is slightly long, but it justifies both the cost and the container-based design, so almost every sentence earns its place.

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 a 5-parameter tool with 0% schema coverage and a real cost side effect, the description covers preconditions, cost, latency, parameter meaning, and the return shape including the filtered_out/all_env_names nuance. Nothing an agent needs to decide whether and how to call it is missing.

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

Parameters5/5

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

Schema coverage is 0%, so the description carries the full burden and does: secret_name's source is named, env identifies the Modal environment, image explains the default and when to override it, timeout_seconds notes the default 300 covers image build, and profile is scoped to this call only. This is meaning the schema's bare types cannot convey.

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 precise verb and resource ('List the KEY NAMES inside a Modal secret') and immediately bounds scope ('never the values'), which separates it cleanly from list_modal_resources and manage_modal_secret. An agent knows exactly what this returns without opening the schema.

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: use list_modal_resources(resource="secrets") to discover secrets, and 'reach for this only when you need to know what is inside one.' It also gives a concrete alternative trigger for the image parameter (when the workspace image builder rejects the server's Python).

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