Skip to main content
Glama
Sign In

twelvebit Analytics

by app.twelvebit
OverviewDiscussionsAdmin

Roll an API key

roll_api_key
Destructive

Replace a site key with a new secret that has the same name and scopes, for example after a leak. The old key stops at once, or after grace_seconds (at most 86400, 24 hours) so a deploy can switch over. The new secret is NOT returned here, so it never enters the chat: the person copies it once in the dashboard (Settings → API & MCP) within 24 hours. Needs the admin scope and confirm: true; without confirm the tool only describes what it would do.

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": {
      "key_id": "<key_id>"
    },
    "name": "roll_api_key"
  }
}

Input Schema

NameRequiredDescriptionDefault
siteNoSite domain (example.com), id or public id (tb_…). Optional with a site key, or when the account has one site.
key_idYesThe key id from list_api_keys.
confirmNoSet to true to really do it. Without it, the tool only describes what it would do.
grace_secondsNoHow long the old key keeps working. Default 0 (stops at once).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and non-idempotent, and the description adds context annotations cannot: the old key stops immediately unless a bounded grace period is set, the new secret is deliberately not returned to the chat, and the human must copy it from Settings → API & MCP within 24 hours. That is exactly the disclosure an agent needs before triggering an irreversible credential rotation.

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?

Three dense sentences, front-loaded with the action and outcome, then timing, then the critical 'secret is not returned' warning and the precondition. No sentence is redundant or out of order.

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 destructive, non-idempotent mutation with no output schema, the description covers what changes, what is destroyed, the timing window, the auth requirement and the confirm gate. The one thing an agent might expect back — the new secret — is explicitly addressed as intentionally withheld.

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 site, key_id, confirm and grace_seconds including the 86400 cap. The description restates the grace/confirm semantics and otherwise only adds the 'same name and scopes' outcome, so this is a baseline 3 with the schema doing the heavy lifting.

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 ('Replace a site key with a new secret') plus the preservation semantics ('same name and scopes'), which cleanly separates it from revoke_api_key and list_api_keys. The 'after a leak' framing tells the agent exactly what situation this tool exists for.

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?

Gives the trigger ('for example after a leak'), the alternative to immediate kill ('grace_seconds ... so a deploy can switch over'), the prerequisites ('Needs the admin scope and confirm: true'), and the dry-run fallback ('without confirm the tool only describes what it would do'). An agent has no inference left to make.

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

All twelvebit Analytics toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources