mailbox-mcp

send_text_letter

Destructive

Prints and mails a plain-text letter composed in chat through mailbox.bot with US Letter formatting; run dry_run first to check exact cost and approval requirements.

Instructions

Mail a letter written as plain text, for letters composed in chat. mailbox.bot sets the text exactly as given on US Letter pages (Times 12 pt, 1-inch margins; no letterhead, logo or signature image) and submits it through send_outbound_mail, so the same scopes, approval, cost caps and proof apply and staff print and mail it. Run with dry_run: true first to see the exact cost; with a live key this spends the account owner's prepaid credits, and a key that requires approval holds the letter until the owner approves it in the dashboard. Requires mailbox_md_version from get_mailbox_md. Up to 15,000 characters of Latin text. For a PDF, letterhead or images, use send_outbound_mail.

Input Schema

Name	Required	Description
`dry_run`	No	true returns the exact cost and checks without creating, charging or mailing anything.
`metadata`	No	Your own reference fields, echoed back in status and webhooks.
`mail_class`	Yes	USPS: first_class (no carrier tracking; mailbox.bot records photo proof), priority (USPS Tracking), certified (USPS tracking plus proof of mailing and delivery), certified_return_receipt (certified plus electronic return receipt). FedEx: fedex_ground, fedex_express (Express Saver, about 3 business days), fedex_2day, fedex_overnight.
`return_zip`	No	Return ZIP code.
`agent_notes`	No	Notes for the owner and the facility.
`letter_text`	Yes	The full letter as plain text: date, greeting, body and sign-off as they should print. Line breaks are kept.
`return_city`	No	Return city.
`return_name`	No	Return name. Defaults to the account's saved return address.
`return_line1`	No	Return street address. Defaults to the account's saved return address.
`return_line2`	No	Return suite or unit.
`return_state`	No	Return state, 2 letters.
`recipient_zip`	Yes	Recipient ZIP code.
`max_cost_cents`	No	Refuse the letter if it would cost more than this, in cents.
`recipient_city`	Yes	Recipient city.
`recipient_name`	No	Recipient name.
`return_company`	No	Return company line.
`recipient_line1`	Yes	Recipient street address.
`recipient_line2`	No	Suite, unit or floor.
`recipient_state`	Yes	Recipient state, 2 letters.
`recipient_company`	No	Recipient company or organization line.
`requires_approval`	No	true holds the letter until the owner approves it in the dashboard.
`mailbox_md_version`	Yes	Current MAILBOX.md version from get_mailbox_md. Required.

Output Schema

Name	Required	Description	Default
`result`	Yes	The send_outbound_mail result: status, cost breakdown, human review and next step.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.0.4Oct 26, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Adds real context beyond the annotations: exact rendering (US Letter, Times 12 pt, 1-inch margins, no letterhead/logo/signature), that it submits through send_outbound_mail so the same scopes/approval/cost caps/proof apply, that staff physically print and mail it, and that live keys spend prepaid credits. It omits explicit statement of irreversibility/idempotency, though destructiveHint and idempotentHint=false already signal those.

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?

Dense but front-loaded, opening with what the tool does before branching into cost, approval, and format constraints. Each sentence carries information, though it is somewhat packed and could be slightly tightened.

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?

An output schema exists, so return values need not be explained. For a 22-parameter mutation tool, the description covers the critical risks – cost, approval gating, character limits, required mailbox_md_version, and rendering constraints – leaving nothing an agent needs to call it correctly.

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 the baseline is 3, but the description adds genuine meaning: the 15,000-character Latin-text limit, the requirement to pass mailbox_md_version from get_mailbox_md, and the dry_run-first workflow. It goes modestly beyond the schema without redundancy.

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+resource ('Mail a letter written as plain text') and scopes it to 'letters composed in chat.' It also names the sibling it is not (send_outbound_mail for PDF/letterhead/images), so an agent can distinguish it before 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 Guidelines5/5

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

Explicit routing: run with dry_run:true first to see exact cost, and use send_outbound_mail instead when the letter needs a PDF, letterhead or images. When-to-use, when-not, and the alternative are all named.

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

Deploy Server