Skip to main content
Glama
Sign In

mailbox.bot

by bot.mailbox
OverviewDiscussionsAdmin

rotate_webhook_endpoint_secret

DestructiveIdempotent

Rotate the signing secret only with explicit operator authorization and confirm_rotation:true. Old signatures overlap for 24 hours; update the receiver's secure secret configuration. Never expose either secret in logs or prompts. Requires webhook.manage. Uses the same bounded control plane and tenant/agent/Live-Sandbox authorization as /api/v1/webhooks/endpoints. Reuse the exact idempotency_key and input after an uncertain mutation. Webhook docs: https://mailbox.bot/docs/webhooks.

Input Schema

NameRequiredDescriptionDefault
endpoint_idYesWebhook endpoint id (UUID) from list_webhook_endpoints.
idempotency_keyYesA new UUID for this one intent; reuse it only to retry the identical request.
confirm_rotationYesMust be true, and only with the operator's explicit authorization. The old secret keeps verifying for 24 hours.
expected_revisionYesThe endpoint's current revision from list_webhook_endpoints; a stale revision is refused so concurrent edits are never overwritten.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / result / properties / endpoint / properties / event_types / items / enum
      Previous value: -[
-  "inbound.received",
-  "inbound.action.requested",
-  "inbound.action.completed",
-  "inbound.pages_ready",
-  "inbound.keywords_matched",
-  "mail.pending_approval",
-  "mail.submitted",
-  "mail.ready",
-  "mail.mailed",
-  "mail.delivered",
-  "mail.failed",
-  "mail.cancelled",
-  "batch.submitted",
-  "batch.completed",
-  "batch.partially_completed",
-  "batch.failed",
-  "batch.cancelled"
-]New value: +[
+  "inbound.received",
+  "inbound.action.requested",
+  "inbound.action.completed",
+  "inbound.pages_ready",
+  "inbound.keywords_matched",
+  "mail.pending_approval",
+  "mail.submitted",
+  "mail.ready",
+  "mail.mailed",
+  "mail.delivered",
+  "mail.failed",
+  "mail.cancelled",
+  "batch.submitted",
+  "batch.completed",
+  "batch.partially_completed",
+  "batch.failed",
+  "batch.cancelled",
+  "batch.piece.scanned",
+  "batch.piece.confirmed"
+]
  2. Changed2 schema fields changed
    • changedOutput schema / properties / result / properties / endpoint / properties / event_types / items / enum
      Previous value: -[
-  "inbound.received",
-  "inbound.action.requested",
-  "inbound.action.completed",
-  "inbound.pages_ready",
-  "inbound.keywords_matched"
-]New value: +[
+  "inbound.received",
+  "inbound.action.requested",
+  "inbound.action.completed",
+  "inbound.pages_ready",
+  "inbound.keywords_matched",
+  "mail.pending_approval",
+  "mail.submitted",
+  "mail.ready",
+  "mail.mailed",
+  "mail.delivered",
+  "mail.failed",
+  "mail.cancelled",
+  "batch.submitted",
+  "batch.completed",
+  "batch.partially_completed",
+  "batch.failed",
+  "batch.cancelled"
+]
    • changedOutput schema / properties / result / properties / endpoint / properties / event_types / maxItems
      Previous value: -16New value: +32
  3. Changed4 schema fields changed
    • addedInput schema / properties / confirm_rotation / description
      Added value: +"Must be true, and only with the operator's explicit authorization. The old secret keeps verifying for 24 hours."
    • addedInput schema / properties / endpoint_id / description
      Added value: +"Webhook endpoint id (UUID) from list_webhook_endpoints."
    • addedInput schema / properties / expected_revision / description
      Added value: +"The endpoint's current revision from list_webhook_endpoints; a stale revision is refused so concurrent edits are never overwritten."
    • addedInput schema / properties / idempotency_key / description
      Added value: +"A new UUID for this one intent; reuse it only to retry the identical request."
  4. Changed4 schema fields changed
    • changedOutput schema / properties / result / properties / endpoint / properties / event_types / items / enum
      Previous value: -[
-  "inbound.received",
-  "inbound.scan_available",
-  "inbound.context_ready",
-  "inbound.rule_matched",
-  "inbound.action_completed",
-  "inbound.action_failed",
-  "mail.submitted",
-  "mail.ready",
-  "mail.mailed",
-  "mail.delivered",
-  "mail.failed",
-  "mail.cancelled",
-  "mail.pending_approval"
-]New value: +[
+  "inbound.received",
+  "inbound.action.requested",
+  "inbound.action.completed",
+  "inbound.pages_ready",
+  "inbound.keywords_matched"
+]
    • changedOutput schema / properties / result / properties / endpoint / properties / status / enum
      Previous value: -[
-  "pending_verification",
-  "active",
-  "paused"
-]New value: +[
+  "active",
+  "paused"
+]
    • removedOutput schema / properties / result / properties / endpoint / properties / verified_at
      Removed value: -{
-  "anyOf": [
-    {
-      "format": "date-time",
-      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ]
-}
    • changedOutput schema / properties / result / properties / endpoint / required
      Previous value: -[
-  "name",
-  "url",
-  "agent_id",
-  "environment",
-  "event_types",
-  "rules",
-  "id",
-  "member_id",
-  "status",
-  "revision",
-  "verified_at",
-  "created_at",
-  "updated_at",
-  "last_delivery_at",
-  "last_http_status",
-  "failure_count",
-  "signing_key_prefix",
-  "previous_key_expires_at"
-]New value: +[
+  "name",
+  "url",
+  "agent_id",
+  "environment",
+  "event_types",
+  "rules",
+  "id",
+  "member_id",
+  "status",
+  "revision",
+  "created_at",
+  "updated_at",
+  "last_delivery_at",
+  "last_http_status",
+  "failure_count",
+  "signing_key_prefix",
+  "previous_key_expires_at"
+]
  5. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already flag destructive, idempotent, and open-world behavior, and the description adds real context beyond them: a 24-hour signature overlap window, the required webhook.manage scope, the shared tenant/agent/Live-Sandbox authorization boundary, an explicit 'never expose either secret in logs or prompts' caution, and idempotent retry semantics. That is the authorization and side-effect detail an agent needs before a destructive call.

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?

The rotation instruction and the confirm_rotation:true gate are front-loaded, and each subsequent sentence carries operational information. A couple of clauses are dense and partly redundant (confirm_rotation:true appears in both sentence one and the schema; the control-plane authorization sentence is verbose), but there is no 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?

With an output schema present, a fully described 4-parameter schema, and rich annotations, the description covers the remaining gaps: permission requirements, destructive-window behavior, idempotent retry, and secret-handling safety. Nothing needed to invoke this correctly is missing, and a docs link is provided for deeper detail.

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 baseline is 3, but the description adds meaning beyond the schema for two parameters: confirm_rotation is gated on explicit operator authorization rather than merely being const true, and idempotency_key reuse is tied to recovering from an uncertain mutation. endpoint_id and expected_revision semantics are left entirely to 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?

The description states a specific verb and resource ('Rotate the signing secret') and scopes it narrowly with 'the signing secret only', which separates it from sibling update_webhook/update_webhook_endpoint that presumably change other endpoint configuration. An agent can identify the operation without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear preconditions: explicit operator authorization, confirm_rotation:true, and the webhook.manage permission. It also covers the retry case ('reuse the exact idempotency_key and input after an uncertain mutation'). It stops short of naming an alternative tool for non-secret changes, which is only implied by 'signing secret only'.

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

All mailbox.bot toolsInspect
Try in Browser
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources