Skip to main content
Glama
gmail-mcp
by gchallen

update_draft

Edit an existing Gmail draft by changing only the fields you specify, while preserving recipients, subject, threading, and attachments unless replaced.

Instructions

Edit an existing draft. Only the fields given change; recipients, subject, threading and attachments are kept otherwise. Giving body or htmlBody replaces the whole body (including any quoted original), and the signature is re-appended. Giving attachments replaces the attachment set; clearAttachments removes them all. Note the draft's message ID changes on every update while the draft ID stays the same.

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": {
      "draftId": "<draftId>"
    },
    "name": "update_draft"
  }
}

Input Schema

NameRequiredDescriptionDefault
ccNo
toNo
bccNo
bodyNoPlain-text body. One line per paragraph, no hard wrapping; Gmail wraps on display and links bare URLs. Markdown does NOT render: for bullets or other formatting supply htmlBody instead.
draftIdYes
subjectNo
htmlBodyNoHTML body, used when the message needs formatting such as <ul><li> lists. When given, "body" becomes the plain-text alternative (derived from the HTML if omitted). Do not include the signature; it is appended.
signatureNoSet false to send without the configured signature. By default the signature (from config.json, GMAIL_SIGNATURE, or the Gmail settings signature) is appended once; a copy typed into the body is de-duplicated.
attachmentsNoFiles to attach, as local paths (preferred: any size up to Gmail's 25 MB total) or base64 objects.
clearAttachmentsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2026.9.2

TDQS

A4.2/5.0
Behavior4/5

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

The description goes well beyond the annotations: it discloses that omitted fields are preserved, that body/htmlBody replaces the whole body including the quoted original, that attachments replace the set and clearAttachments wipes them, and that the message ID rotates while the draft ID is stable. This is exactly the kind of side-effect detail annotations cannot carry. It stops short of naming permission/scope requirements.

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?

Four sentences, front-loaded with the action, then layered from coarse (partial update) to fine (body replacement, attachment replacement, ID rotation). No filler and no repetition of schema text.

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?

For a 10-parameter mutation tool with no output schema and only generic annotations, the description covers the risky semantics an agent most needs. It omits auth/scope requirements and what happens if no editable fields are supplied, which keeps it from being fully complete.

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?

With only 40% schema description coverage across 10 params, the description compensates by explaining the interaction of body vs htmlBody, signature re-appending, attachments replacement, and clearAttachments. The ad-hoc fields (to, cc, bcc, subject) get no explanation, but their meaning is self-evident from the names.

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?

"Edit an existing draft" is a specific verb plus resource, and the rest of the description nails down the scope of the edit (partial field update, body replacement, attachment replacement). It is unambiguously distinct from create_draft, delete_draft, and send_draft in the sibling list.

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

Usage Guidelines3/5

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

Usage context is implied (modify a draft that already exists) and the mutation semantics tell an agent how to combine fields, but there is no explicit when-to-use versus alternatives such as create_draft or send_draft, and no stated preconditions.

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