q-ring

Overview Schema Source Related Servers Discussions Admin

set_secret

DestructiveIdempotent

Create or overwrite a single secret key in q-ring, with optional TTL, environment-specific values, tags, and rotation hints.

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

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']. Replaces the existing tags; omit to keep them.
`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'.
`clearTags`	No	Remove the secret's existing tags. Without it (and without `tags`), existing tags and description are kept.
`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.

Changed2 schema fields changedv0.19.0Nov 6, 2026

addedInput schema / properties / clearTags

Added value: +{
+  "description": "Remove the secret's existing tags. Without it (and without `tags`), existing tags and description are kept.",
+  "type": "boolean"
+}

changedInput schema / properties / tags / description

Previous value: -"Tag list for filtering and hook matching. Example: ['production', 'payments']."New value: +"Tag list for filtering and hook matching. Example: ['production', 'payments']. Replaces the existing tags; omit to keep them."

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.4/5.0

Behavior4/5

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

Annotations already declare destructive=true and idempotent=true, so the safety profile is known; the description still adds real value by disclosing the overwrite target (same key/scope), the audit-log write event, hook triggering, and tool-policy gating. It also specifies the exact confirmation string, including the variant emitted when `env` is set. It stops short of covering failure modes or permission requirements, which keeps it from a 5.

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 purpose, then alternatives, then side effects, then return shape — a sensible order with no filler sentences. It is dense and reads as one long block with a slightly over-long return-format clause, so it is efficient but not maximally scannable.

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 14-parameter mutation tool with no output schema, the description covers what an agent needs: write semantics, overwrite risk, audit/hook side effects, policy gating, and the literal return value. Nothing material is left to inference.

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 carries the parameter semantics and the baseline applies. The description reinforces the `env` superposition model and ties it to the alternate return string, but it does not explain precedence or interaction between the 14 parameters (for example tags vs clearTags vs description retention) beyond what the schema already states.

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 and resource: "Create or overwrite a single secret value," and immediately enumerates the scope of the write (TTL/decay, per-env superposition, description, tags, rotation hints). The explicit contrast with import_dotenv, generate_secret, and entangle_secrets lets an agent distinguish this from every nearby sibling without opening a 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?

States the selection rule directly: use this to add or update one key at a time, and names three concrete alternatives with the conditions that select them (bulk ingest, generate-and-store, duplication avoidance). The only minor gap is that it does not say when to prefer `promote_secret` or `rotate_secret`, but the key routing decisions are covered.

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