Skip to main content
Glama
I4cTime

q-ring

by I4cTime
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

get_secret

Read-onlyIdempotent

Read the plaintext value of a single q-ring secret to call an external API or inject the credential into a runtime.

Instructions

[secrets] Read the plaintext value of a single secret from the q-ring keyring. Use when an agent needs the actual credential to call an external API or inject into a runtime; prefer inspect_secret to see metadata only, has_secret for presence-only checks, and exec_with_secrets to run a command without exposing the value to chat. Side effects: collapses superposition (selects the per-env state) and writes a 'read' event to the audit log (observer effect). Subject to project tool/key policy and may be denied with a 'Policy Denied' message. Returns JSON { ok, data: { key, value } } on success or an error message if missing/blocked.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
envNoEnvironment slug used to collapse superposition when a secret has multiple per-env states. Examples: 'dev', 'staging', 'prod'. If omitted, the secret's defaultEnv is used.
keyYesExact secret key name as stored in the keyring (case-sensitive). Example: 'OPENAI_API_KEY'.
orgIdNoOrganization identifier for org-scoped secrets. Required only when scope='org'. Example: 'acme-corp'.
scopeNoWhere the secret lives. 'global' = user keyring (default if omitted on reads), 'project' = scoped to projectPath, 'team' = team-shared (needs teamId), 'org' = org-shared (needs orgId).
teamIdNoTeam identifier for team-scoped secrets. Required only when scope='team'. Example: 'acme-platform'.
projectPathNoAbsolute path to the project root for project-scoped secrets and policy resolution. Defaults to the MCP server's current working directory when omitted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.11.7
    • changedInput schema / properties / env / description
      Previous value: -"Environment for superposition collapse (e.g., dev, staging, prod)"New value: +"Environment slug used to collapse superposition when a secret has multiple per-env states. Examples: 'dev', 'staging', 'prod'. If omitted, the secret's defaultEnv is used."
    • changedInput schema / properties / key / description
      Previous value: -"The secret key name"New value: +"Exact secret key name as stored in the keyring (case-sensitive). Example: 'OPENAI_API_KEY'."
    • changedInput schema / properties / orgId / description
      Previous value: -"Org identifier for org-scoped secrets"New value: +"Organization identifier for org-scoped secrets. Required only when scope='org'. Example: 'acme-corp'."
    • changedInput schema / properties / projectPath / description
      Previous value: -"Project root path for project-scoped secrets"New value: +"Absolute path to the project root for project-scoped secrets and policy resolution. Defaults to the MCP server's current working directory when omitted."
    • changedInput schema / properties / scope / description
      Previous value: -"Scope: global, project, team, or org"New value: +"Where the secret lives. 'global' = user keyring (default if omitted on reads), 'project' = scoped to projectPath, 'team' = team-shared (needs teamId), 'org' = org-shared (needs orgId)."
    • changedInput schema / properties / teamId / description
      Previous value: -"Team identifier for team-scoped secrets"New value: +"Team identifier for team-scoped secrets. Required only when scope='team'. Example: 'acme-platform'."
  2. Changed4 schema fields changedv0.11.5
    • addedInput schema / properties / orgId
      Added value: +{
+  "description": "Org identifier for org-scoped secrets",
+  "type": "string"
+}
    • changedInput schema / properties / scope / description
      Previous value: -"Scope: global or project"New value: +"Scope: global, project, team, or org"
    • changedInput schema / properties / scope / enum
      Previous value: -[
-  "global",
-  "project"
-]New value: +[
+  "global",
+  "project",
+  "team",
+  "org"
+]
    • addedInput schema / properties / teamId
      Added value: +{
+  "description": "Team identifier for team-scoped secrets",
+  "type": "string"
+}
  3. First observedv0.1.0

TDQS

A4.6/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 it collapses superposition, writes a 'read' audit event, is subject to policy that may return 'Policy Denied', and returns a specific JSON shape. These are non-obvious behavioral traits the annotations (readOnly/idempotent/non-destructive) do not convey.

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 purpose followed by alternatives and side effects; every sentence earns its place. It is dense but not padded, though slightly long for a read tool.

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?

Despite no output schema, the description supplies the return contract ('Returns JSON { ok, data: { key, value } }') and error behavior, plus policy and audit side effects. An agent has everything needed to call and interpret this tool.

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 all six parameters are already well documented in the schema. The description adds only the general notion of per-env superposition, which the env schema field already explains. Baseline 3 is appropriate when the schema carries the load.

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 ('Read the plaintext value of a single secret') and immediately distinguishes itself from siblings by naming inspect_secret, has_secret, and exec_with_secrets. An agent knows exactly what this tool 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 states the trigger condition ('when an agent needs the actual credential to call an external API or inject into a runtime') and routes to the right alternative for each other need (metadata, presence check, indirect execution). This is textbook when/when-not guidance.

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

Deploy Server

Other Tools