mailbox-mcp

rotate_webhook_endpoint_secret

DestructiveIdempotent

Rotate a webhook endpoint's signing secret only with explicit operator authorization and confirm_rotation:true. Old signatures remain valid for 24 hours; update the receiver's secret configuration.

Instructions

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

Name	Required	Description
`endpoint_id`	Yes	Webhook endpoint id (UUID) from list_webhook_endpoints.
`idempotency_key`	Yes	A new UUID for this one intent; reuse it only to retry the identical request.
`confirm_rotation`	Yes	Must be true, and only with the operator's explicit authorization. The old secret keeps verifying for 24 hours.
`expected_revision`	Yes	The endpoint's current revision from list_webhook_endpoints; a stale revision is refused so concurrent edits are never overwritten.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.4Oct 26, 2026

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
```

Addedv1.0.3Oct 12, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the destructive/idempotent hints: it discloses the 24-hour overlap window for old signatures, the required webhook.manage scope, the no-logging/no-prompt handling constraint, tenant and Live-Sandbox authorization scope, and the retry contract. That is exactly the context the annotations alone cannot convey.

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?

Front-loads the authorization gate and confirmation flag in the first clause, then layers safety, permission, and retry details in short declarative sentences. Every sentence carries a distinct operational constraint with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers permissions, reversibility window, side effects, and retry semantics, and links to docs; an output schema handles the return shape. The one gap is that it never says the new secret is surfaced only in the response, which is the most important handling detail for a rotation 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 coverage is 100%, so every parameter is already documented in the schema. The description reinforces confirm_rotation:true and idempotency_key reuse, but those points duplicate the schema text, and expected_revision is not discussed at all.

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 ('Rotate the signing secret') and makes clear it is the secret-rotation operation, not the general endpoint edit or test operations performed by update_webhook_endpoint or test_webhook_endpoint. An agent can select it 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?

Sets a clear precondition ('only with explicit operator authorization') and a retry rule ('reuse the exact idempotency_key and input after an uncertain mutation'), plus the follow-up action of updating the receiver's configuration. It never names a sibling alternative (e.g., that update_webhook_endpoint handles non-secret changes), so routing guidance is implied rather than explicit.

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

Deploy Server