get_emailGet a single email by public id (msg_…): its status, and in delivery the recipient's mail server, its exact reply (250 … when accepted, 5xx … when refused), TLS and the latest deferral. delivered_at minus created_at is how long it took to land.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Email id (msg_…) |
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The email |
Changes observed during successful MCP inspections.
Output schema / properties / email / properties / held_back / items / properties / reason / descriptionPrevious value: -"Why: invalid_address (cannot exist), no_mail_server (domain takes no email), previously_bounced (hard-bounced for a Groundmail sender in the last 90 days) or mailbox_not_found"New value: +"Why: invalid_address (cannot exist), no_mail_server (domain takes no email), previously_bounced (hard-bounced for a Groundmail sender in the last 90 days), mailbox_not_found, or likely_bot_signup (looks like a bot sign-up; only when the send opted in)"Output schema / properties / email / properties / batch_idAdded value: +{
+ "description": "The batch send it came from (batch_…), for get_batch and cancel_batch; null for a single send",
+ "type": [
+ "string",
+ "null"
+ ]
+}Output schema / properties / email / properties / deliveryAdded value: +{
+ "description": "What the recipient's mail server said about the latest delivery attempt. Null until an attempt reports one, and for test emails. delivered_at minus created_at is how long it took to land",
+ "properties": {
+ "deferred_at": {
+ "description": "When the latest deferral happened (ISO 8601)",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "deferred_response": {
+ "description": "Its reply to the latest deferral (a 4xx such as greylisting; delivery is retried); null when none",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "receiving_server": {
+ "description": "Hostname of the recipient's mail server, e.g. gmail-smtp-in.l.google.com",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "response": {
+ "description": "Its exact SMTP reply to the latest attempt that finished: 250 … when it accepted the email, 5xx … when it refused it",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "tls": {
+ "description": "Whether the connection used TLS; null when the attempt did not say",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "receiving_server",
+ "response",
+ "tls",
+ "deferred_response",
+ "deferred_at"
+ ],
+ "type": [
+ "object",
+ "null"
+ ]
+}Output schema / properties / email / properties / streamAdded value: +{
+ "description": "Mail stream it went out on: transactional, product or newsletter (each sends from its own IPs)",
+ "type": "string"
+}Output schema / properties / email / properties / tenantAdded value: +{
+ "description": "External id of the tenant the email was sent as. Present only when it was sent as a tenant",
+ "type": [
+ "string",
+ "null"
+ ]
+}Output schema / properties / email / properties / testAdded value: +{
+ "description": "True when the email never reached the mail server: sent with a test key (gm_test_…) or only to simulator addresses. Its status and events are simulated",
+ "type": "boolean"
+}Output schema / properties / email / properties / held_backAdded value: +{
+ "description": "Recipients Groundmail validation held back before sending, with why; empty when none were",
+ "items": {
+ "properties": {
+ "email": {
+ "description": "The held-back address",
+ "type": "string"
+ },
+ "reason": {
+ "description": "Why: invalid_address (cannot exist), no_mail_server (domain takes no email), previously_bounced (hard-bounced for a Groundmail sender in the last 90 days) or mailbox_not_found",
+ "type": "string"
+ }
+ },
+ "required": [
+ "email",
+ "reason"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / email / properties / bounce_typeAdded value: +{
+ "description": "Why it bounced: hard (address cannot receive; suppressed) or block (the receiving server refused the sender for reputation or policy; address not suppressed, safe to retry later). Null if it did not bounce",
+ "enum": [
+ "hard",
+ "block",
+ null
+ ],
+ "type": [
+ "string",
+ "null"
+ ]
+}Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description still adds real value: it enumerates what the response carries (status, recipient mail server, exact SMTP reply with 250 vs 5xx meaning, TLS, latest deferral). It also gives an interpretive rule — delivered_at minus created_at equals landing latency — that an agent could not derive from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence: identity and lookup key first, then the returned telemetry, then the interpretive note. Dense but every clause adds information, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with an output schema and full annotation coverage, the description supplies more than enough: what identifies the record and what the delivery fields mean. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the description's "public id (msg_…)" essentially restates the schema's own "Email id (msg_…)" text. Baseline 3 applies since the schema carries the parameter burden; no extra id syntax or format detail is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Get a single email by public id (msg_…)") and even names the parts of the object surfaced (status, delivery diagnostics). The singular-lookup framing implicitly separates it from list_emails, but no sibling is named explicitly, so it lands short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the agent must already hold a msg_… id, which suggests it is a follow-up to list_emails or send_email. There is no explicit when-to-use/when-not statement and no routing hint to list_emails for discovering ids.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.