Skip to main content
Glama

Find secret keys

find_secret_keys
Read-onlyIdempotent

Search and compare secret key names, never values: across every project, against names you already have, through one key's history, or between two environments. To list all keys of one environment use list_project_items item secrets; to read a value use reveal_values. Actions (arguments besides action):

  • search (query; optional project): where keys matching query live, in every project this token reaches or only project. query is a case-insensitive substring or a * pattern (NEXT_PUBLIC_*, *_URL). At most 200 matches, not paged.

  • check (project, keys; optional environment): for exact names you already have (from .env.example, say), the environments each exists in.

  • history (project, environment, key): the key's versions, newest first, with who changed it and when. Paged: call again with nextCursor until it is null. Pass a version to manage_secrets action restore.

  • diff (project, from, to): keys only in from, only in to, and in both with different values, compared on the server. Protected, sealed and restricted keys are only counted, in hidden. Run it before manage_secrets action copy. An unknown or unreachable project or environment fails with a message. search, check and history need projects:read; diff needs secrets:read on both environments and is audited.

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>"
    },
    "name": "find_secret_keys"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNodiff only: the second environment
keyNohistory only: the key whose versions to list
fromNodiff only: the first environment
keysNocheck only: exact key names to look for, 1 to 500
limitNohistory only: versions per page, 1 to 200. Default 100.
queryNosearch only: a key substring matched case-insensitively (database), or a pattern where * matches anything (NEXT_PUBLIC_*, *_URL)
actionYesWhat to ask
cursorNohistory only: the nextCursor of the previous page
searchNohistory only: filters the versions by their number (not the key; use query for action search)
projectNocheck, history and diff: required. search: optional, limits the search to one project
environmentNohistory: required, the key's environment. check: optional, only this environment

Output Schema

NameRequiredDescriptionDefault
toNo
keyNo
fromNo
keysNo
queryNo
hiddenNoSealed, protected or restricted keys, counted and never named
currentNoThe current version number
matchesNo
projectNo
onlyInToNo
versionsNo
differentNoKeys present in both with a different value; names only
truncatedNoMore matches exist than are listed
nextCursorNoPass as cursor to read the next page; null at the end
onlyInFromNo
environmentNo
environmentsNo
projectsSearchedNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / query / description
      Previous value: -"search only: key substring, case-insensitive, or a pattern with *"New value: +"search only: a key substring matched case-insensitively (database), or a pattern where * matches anything (NEXT_PUBLIC_*, *_URL)"
  2. Added

TDQS

A4.9/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations by disclosing that values are never returned, that search caps at 200 matches without paging, that history is cursor-paged until nextCursor is null, that protected/sealed/restricted keys appear only as counts in 'hidden', and the differing permission scopes (projects:read vs secrets:read) with diff being audited. It also names the failure mode for unknown or unreachable projects.

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 purpose sentence, then alternative-routing, then a bulleted action list with arguments parenthesized per action. Dense but every clause carries operational information; no restatement of the name or 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 11-parameter, four-mode tool this covers limits, pagination, permissions, audit behavior, and redaction policy, while an output schema already documents return shapes. Nothing an agent needs to invoke the correct action with correct arguments is missing.

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 earns more by mapping parameters to actions ('check (project, keys; optional environment)', 'diff (project, from, to)') and by explaining query semantics with pattern examples (NEXT_PUBLIC_*, *_URL) and the intent behind keys ('from .env.example'). The one gap is the 'search' parameter filtering versions by number, which is only clarified in the schema.

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 — 'Search and compare secret key names' — and immediately scopes it with 'never values', which is the decisive distinction from sibling reveal_values. The four supported modes (every project, against known names, one key's history, two environments) make the tool's reach unambiguous.

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 to alternatives: 'To list all keys of one environment use list_project_items item secrets; to read a value use reveal_values', and prescribes ordering ('Run it before manage_secrets action copy', 'Pass a version to manage_secrets action restore'). Each action's selection condition is spelled out rather than implied.

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