mailbox-mcp

estimate_batch_mail

Read-onlyIdempotent

Generate a precise cost estimate for your batch of mail before printing. Specify quantity, size, printing options, and mailing class to determine the total price and per-piece rates.

Instructions

Price a batch before any file exists. Per piece: printing, card stock or paper, the envelope where one is used, the address label, handling and USPS postage. First-Class: 4×6 postcard $1.05, 6×9 postcard $1.35 (both sides in full color; a one-page design gets an address side printed with the return address), letter $1.15 (1 sheet) or $1.35 (2–3 sheets), flyer $1.15, pamphlet $1.95 (4–8 pages) or $2.75 (9–16 pages). Marketing Mail (200+ recipients, not open yet): postcards 85¢, letters and flyers 89¢, pamphlets $1.75. Color on letters, flyers and pamphlets adds 16¢ per color page; duplex is included (two pages per sheet). Volume: 5 % off at 500+, 10 % at 1,000+. No piece is priced below its minimum, our cost to make and mail it plus 5¢: two-sided color, extra sheets, the volume discount and account prices all stop there, and the estimate says when it applied. Postcards from 1 piece (a $2.00 small-batch fee under 10); letters, flyers and pamphlets from 10 (fewer: POST /v1/mail); up to 10,000 per batch. The estimate is the exact amount confirm debits. Sandbox keys get the same numbers with credits_required_cents 0.

Input Schema

Name	Required	Description
`color`	No	Color printing for letters, flyers and pamphlets, charged per color page. Postcards are always full color.
`duplex`	No	Print both sides of each sheet. Default false.
`quantity`	Yes	Recipients: postcards from 1 (a $2.00 small-batch fee under 10), letters, flyers and pamphlets from 10 (fewer: send_outbound_mail); up to 10,000.
`mail_type`	Yes	postcard_4x6, postcard_6x9, letter (1–3 pages, 6 with duplex), flyer (1 page), pamphlet_light (4–8 pages), pamphlet_heavy (9–16 pages).
`page_count`	No	Pages in the template PDF (1 for an image). Default 1.
`mailing_class`	No	first_class (USPS First-Class Mail, 1–5 days, forwarded and returned; the default) or marketing_mail (USPS Marketing Mail, 3–10 days, 200+ recipients; not open until the facility's USPS permit is active). The class is USPS postage, not a description of the content: bills, statements and personal correspondence must go first_class.

Output Schema

Name	Required	Description	Default
`result`	Yes	The estimate in US cents: per piece, volume discount, total, and what a live key would be charged.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.0.4Oct 26, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, and the description adds genuinely useful behavior: volume discounts (5%/10%), the per-piece price floor, that minimums suppress discounts, and that sandbox keys return credits_required_cents 0. It stops short of describing latency or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in one sentence, but the bulk is a dense pricing table that largely restates what the tool itself computes and returns — and an output schema exists, so return values need no narration here. Many exact price points and edge rules are not needed for tool selection, making it far longer than its selection job requires.

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?

Given read-only annotations and an existing output schema, the definition is complete enough: it establishes what the number represents (exact debit amount), the batch size ceiling (10,000), sandbox behavior, and the minimum-price floor. It slightly over-delivers on return content but leaves no blocking gap for correct invocation.

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 baseline is 3, but the description adds pricing meaning the schema does not: color adds 16¢ per color page, duplex is included (two pages per sheet), postcards are always full color, and mailing_class choice materially changes the price base. That is real added semantics over the field descriptions.

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?

Opens with a specific verb+resource+scope: 'Price a batch before any file exists.' That is clearly distinguishable from create_batch_mail and confirm_batch_mail, and the estimate/price framing separates it from quote_outbound_mail for one-off mail.

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?

Establishes the pre-file timing, gives quantity thresholds (postcards from 1, letters/flyers/pamphlets from 10) and routes small orders to send_outbound_mail, plus links the estimate to confirm_batch_mail by saying it is 'the exact amount confirm debits.' It does not explicitly state when-not to use it beyond those thresholds, so it falls short of a full 5.

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

Deploy Server