MCP Emails

Edit a pending send

approval_update

Idempotent

Update the subject or body of an email waiting for human approval before it is reviewed and sent.

Instructions

Change the subject or body of a send that is waiting for human approval. The message still has to be approved afterwards, and the reviewer sees the edited version. Subject can only be set on operations that carry one (email_send, schedule_create).

Input Schema

TableJSON Schema

Name	Required	Description
`subject`	No	Replacement subject line.
`body_html`	No	Replacement HTML body.
`body_text`	No	Replacement plain-text body. Unless body_html is supplied in the same call, the HTML part is regenerated from this text so both parts of the message say the same thing. Include the signature if the body you are replacing had one.
`approval_id`	Yes	The approval_id returned by a gated send (status: "pending_approval").

Output Schema

TableJSON Schema

Name	Required	Description
`card`	No	Which card this envelope renders: 'outbound_review' or 'receipt'.
`state`	No	Where the request stands: pending, approved, rejected, expired or sent.
`dashboard_url`	No	Absolute link to the signed-in approvals page. Always present, and the one link that still works when the rest of the envelope cannot be parsed.
`schema_version`	No	Card envelope version. A client that does not know this version should fall back to dashboard_url.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 10, 2026

changedInput schema / properties / body_text / description

Previous value: -"Replacement plain-text body."New value: +"Replacement plain-text body. Unless body_html is supplied in the same call, the HTML part is regenerated from this text so both parts of the message say the same thing. Include the signature if the body you are replacing had one."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "card": {
+      "description": "Which card this envelope renders: 'outbound_review' or 'receipt'.",
+      "type": "string"
+    },
+    "dashboard_url": {
+      "description": "Absolute link to the signed-in approvals page. Always present, and the one link that still works when the rest of the envelope cannot be parsed.",
+      "type": "string"
+    },
+    "schema_version": {
+      "description": "Card envelope version. A client that does not know this version should fall back to dashboard_url.",
+      "type": "integer"
+    },
+    "state": {
+      "description": "Where the request stands: pending, approved, rejected, expired or sent.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedv1.0.4Aug 30, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations indicate readOnlyHint=false (mutation) and idempotentHint=true (safe to retry), which description does not contradict. The description adds useful behavior: the message still needs approval, reviewer sees edited version, and subject can only be set on certain operations. This satisfies the bar.

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 concise sentences, each providing essential info without fluff. Front-loads the purpose, then critical behavior, then a constraint on subject. No waste.

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?

Output schema exists, so return values are covered. Description covers the key preconditions and side effects. Lack of explicit prerequisites (e.g., permission to edit) is minor, so a 4 is fair.

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% with detailed descriptions for all parameters, including the regeneration rule for body_text. The description adds minimal parameter detail beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'Change' with resource ('subject or body of a send') and explicit context of pending approval. It distinguishes from siblings like approval_decide and approval_review by focusing on editing rather than approval action.

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?

States when to use: for sends waiting for approval, must be approved afterwards, and reviewer sees edited version. It does not explicitly name alternatives or when not to use, but the context is fairly clear.

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