q-ring

Overview Schema Source Related Servers Discussions Admin

set_secret

DestructiveIdempotent

Create or overwrite a single secret value with optional TTL, per-environment states, tags, and rotation hints. Use for one-time updates; choose bulk import or generation tools for batch needs.

Instructions

[secrets] Create or overwrite a single secret value, optionally with TTL/decay, per-env superposition, description, tags, and rotation hints. Use to add or update one key at a time; prefer import_dotenv for bulk .env ingest, generate_secret (with saveAs) to generate-and-store in one step, and entangle_secrets instead of duplicating the same value under two keys. Mutates the keyring (overwrites any existing value at the same key/scope), writes a 'write' event to the audit log, and triggers any matching hooks. Subject to tool policy. Returns a short confirmation text like '[scope] KEY saved' (or '[scope] KEY set for env:NAME' when env is provided).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`env`	No	If set, writes this value to the named per-env state (superposition) instead of the default slot. Existing default value is preserved as state 'default'. Example: 'prod'.
`key`	Yes	Secret key name (UPPER_SNAKE_CASE recommended). Example: 'STRIPE_SECRET_KEY'.
`tags`	No	Tag list for filtering and hook matching. Example: ['production', 'payments'].
`orgId`	No	Organization identifier for org-scoped secrets. Required only when scope='org'. Example: 'acme-corp'.
`scope`	No	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).	global
`value`	Yes	The secret value to store. Stored as-is; never logged or echoed. May be empty only when `env` is provided to register a new env without a default.
`teamId`	No	Team identifier for team-scoped secrets. Required only when scope='team'. Example: 'acme-platform'.
`ttlSeconds`	No	Quantum decay window in seconds. After this many seconds the secret is marked expired (still readable, but `has_secret` returns false and `health_check` flags it). Omit for no decay.
`description`	No	Free-text human-readable description shown in `inspect_secret` and the dashboard.
`projectPath`	No	Absolute path to the project root for project-scoped secrets and policy resolution. Defaults to the MCP server's current working directory when omitted.
`rotationFormat`	No	Format used by `agent_scan --autoRotate` and `rotate_secret` when this secret expires. Pick the format that matches the upstream service's accepted shape.
`rotationPrefix`	No	Literal prefix prepended on auto-rotation (only used with rotationFormat 'api-key' or 'token'). Example: 'sk-'.
`rotateEveryDays`	No	Rotation reminder interval in days (1-3650). `inspect_secret` then reports rotation state ok / due-soon / overdue, and the dashboard and `qring rotate:due` surface it. Purely a reminder — nothing rotates automatically. Omit to keep the existing interval.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.18.0Sep 27, 2026

addedInput schema / properties / rotateEveryDays

Added value: +{
+  "description": "Rotation reminder interval in days (1-3650). `inspect_secret` then reports rotation state ok / due-soon / overdue, and the dashboard and `qring rotate:due` surface it. Purely a reminder — nothing rotates automatically. Omit to keep the existing interval.",
+  "maximum": 3650,
+  "minimum": 1,
+  "type": "integer"
+}

Changed12 schema fields changedv0.11.7Apr 29, 2026

changedInput schema / properties / description / description

Previous value: -"Human-readable description"New value: +"Free-text human-readable description shown in `inspect_secret` and the dashboard."

changedInput schema / properties / env / description

Previous value: -"If provided, sets the value for this specific environment (superposition)"New value: +"If set, writes this value to the named per-env state (superposition) instead of the default slot. Existing default value is preserved as state 'default'. Example: 'prod'."

changedInput schema / properties / key / description

Previous value: -"The secret key name"New value: +"Secret key name (UPPER_SNAKE_CASE recommended). Example: 'STRIPE_SECRET_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 / rotationFormat / description

Previous value: -"Format for auto-rotation when this secret expires"New value: +"Format used by `agent_scan --autoRotate` and `rotate_secret` when this secret expires. Pick the format that matches the upstream service's accepted shape."

changedInput schema / properties / rotationPrefix / description

Previous value: -"Prefix for auto-rotation (e.g. 'sk-')"New value: +"Literal prefix prepended on auto-rotation (only used with rotationFormat 'api-key' or 'token'). Example: 'sk-'."

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 / tags / description

Previous value: -"Tags for organization"New value: +"Tag list for filtering and hook matching. Example: ['production', 'payments']."

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'."

changedInput schema / properties / ttlSeconds / description

Previous value: -"Time-to-live in seconds (quantum decay)"New value: +"Quantum decay window in seconds. After this many seconds the secret is marked expired (still readable, but `has_secret` returns false and `health_check` flags it). Omit for no decay."

changedInput schema / properties / value / description

Previous value: -"The secret value"New value: +"The secret value to store. Stored as-is; never logged or echoed. May be empty only when `env` is provided to register a new env without a default."

Changed4 schema fields changedv0.11.5Apr 27, 2026

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"
+}

Changed2 schema fields changedv0.1.1Mar 22, 2026

addedInput schema / properties / rotationFormat

Added value: +{
+  "description": "Format for auto-rotation when this secret expires",
+  "enum": [
+    "hex",
+    "base64",
+    "alphanumeric",
+    "uuid",
+    "api-key",
+    "token",
+    "password"
+  ],
+  "type": "string"
+}

addedInput schema / properties / rotationPrefix

Added value: +{
+  "description": "Prefix for auto-rotation (e.g. 'sk-')",
+  "type": "string"
+}

First observedv0.1.0Mar 19, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already mark the operation as destructive and idempotent, but the description adds concrete behavioral context: overwriting the same key/scope, writing a 'write' audit event, triggering hooks, and being subject to policy. It also discloses that values are stored as-is and never logged or echoed, which is important side-effect information.

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?

The description is front-loaded with the core purpose, then covers usage, behavior, policy, and return format without redundancy. Every sentence contributes operationally useful information.

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 complex 13-parameter mutation tool with no output schema, the description covers purpose, alternatives, side effects, policy constraints, and the exact confirmation return text. Nothing essential is left for the agent to guess.

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 all 13 parameters thoroughly. The description adds only a compact framing around TTL/decay, per-env superposition, tags, and rotation hints, but it does not materially expand the semantics beyond what the schema already provides.

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?

The description states the exact action ('Create or overwrite a single secret value') and resource, while immediately distinguishing itself from bulk ingest, generate-and-store, and secret-entangling siblings. An agent can tell precisely what set_secret is for 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?

It explicitly says to use this tool to add or update one key at a time and names import_dotenv, generate_secret, and entangle_secrets as alternatives for different workflows. This is clear when-to-use and when-not-to-use guidance.

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

set_secret

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools