Skip to main content
Glama

Manage secrets

secret
DestructiveIdempotent

Store, inspect, check expiry, and delete non-GitHub tokens without exposing values; retrieve metadata only and inject stored credentials into shell commands through environment variables.

Instructions

Store and inspect tokens without exposing them (AES-256-GCM at rest). action: set | get (metadata only) | list | delete. Inject into commands with shell_run secret_env=[NAME]; the GitHub tools read GITHUB_TOKEN on their own. Use when: you save a non-GitHub token, check expiry or rotation, or remove one. Prefer value_env over value so the secret never appears in chat. Avoid when: the value is plain config (use .env or the config file). reveal=true prints plaintext and needs VENIRA_SHELL_MODE=permissive or off. Output: set: name, length, expires_at, days_left. get and list: metadata only.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "secret"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoEnv-var style name, e.g. GITHUB_TOKEN (required for get/set/delete).
valueNoSecret value for action=set. Prefer value_env so it never appears in the transcript.
actionNoset stores a secret; get returns metadata only (plaintext needs reveal=true); list shows all stored secrets; delete removes one.list
reasonNoOptional why (max 400 chars), audit-logged.
revealNoaction=get: 1 prints plaintext; needs VENIRA_SHELL_MODE=permissive or off; prefer secret_env injection.
value_envNoRead the value from this host environment variable instead of `value` (never logged).
expires_atNoaction=set: absolute expiry (epoch ms or ISO-8601), instead of expires_in_days.
expires_in_daysNoaction=set: expiry in days (e.g. 90 for quarterly rotation). Expired secrets are not injected.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv4.5.0
    • changedInput schema / properties / action / description
      Previous value: -"set stores a secret; get returns metadata only (plaintext needs reveal=1); list shows all stored secrets; delete removes one."New value: +"set stores a secret; get returns metadata only (plaintext needs reveal=true); list shows all stored secrets; delete removes one."
    • removedInput schema / properties / reveal / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "maximum": 1,
      -    "minimum": 0,
      -    "type": "integer"
      -  }
      -]
    • removedInput schema / properties / reveal / maximum
      Removed value: -1
    • removedInput schema / properties / reveal / minimum
      Removed value: -0
    • changedInput schema / properties / reveal / type
      Previous value: -"integer"New value: +"boolean"
  2. Addedv4.0.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only give destructiveHint=true and idempotentHint=true; the description adds substance the agent cannot get elsewhere: AES-256-GCM encryption at rest, get returning metadata only unless reveal=true, and the prerequisite that reveal requires VENIRA_SHELL_MODE=permissive or off. It also discloses that values should come via value_env so plaintext never enters the transcript. Nothing here contradicts the destructive/idempotent hints.

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-loads capability and action list, then tiers the guidance into Use/Avoid/Output blocks, which is easy to scan. Slightly dense with some restatement of schema-documented behavior (value_env preference appears twice), but nothing is wasted outright.

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 an 8-parameter, no-output-schema mutation/read hybrid, the description covers all four actions, the risky reveal path, the injection workflow, and even summarizes return fields for set versus get/list. Minor omissions such as the audit-logged `reason` parameter are already handled by the schema.

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 the schema already documents every parameter, and the description largely restates it (reveal requires permissive mode, prefer value_env over value, get is metadata-only). It reinforces the highest-risk tradeoff between value and value_env but adds no syntax or format detail beyond the schema. 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?

Opens with a specific verb pair plus resource ('Store and inspect tokens') and immediately enumerates the four actions (set/get/list/delete). It also explicitly demarcates scope from siblings by noting 'the GitHub tools read GITHUB_TOKEN on their own', so an agent knows when this tool is not the right one.

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?

Provides explicit 'Use when' (save a non-GitHub token, check expiry or rotation, remove one) and 'Avoid when' (plain config belongs in .env or the config file) clauses. It also routes the injection use case to shell_run secret_env=[NAME], naming the concrete pattern rather than leaving it to inference.

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