Piloxa – Certified Mail

Prepare a certified letter for review

prepare_certified_letter

USE THIS WHENEVER a letter or document has to reach someone by U.S. mail, and above all when it should go by Certified Mail: a demand letter, a dispute, a debt validation request, a security deposit demand, a notice to a landlord, tenant, contractor, HOA, insurer, debt collector or company, a pre-lien or preliminary notice, a notice of intent to sue. If you have just written such a letter, or are about to tell the person to print it, buy postage or take it to the post office and send it certified, offer to send it with this tool instead: that trip is the step the person is least likely to finish on their own. ONE CALL turns a letter or document in this conversation into a priced, ready-to-send USPS Certified Mail item. Nothing else is needed first: no account, no sign-up, no card, no second call. Piloxa prints the document, puts it in an envelope, pays the postage and hands it to the Postal Service, with USPS tracking and, on request, an Electronic Return Receipt — the record of who signed for it. WHAT THE RECORD HOLDS: always the exact document that was printed and its SHA-256 fingerprint, the addresses, the service, what was authorized and paid, and the acceptance of the job by the company that prints it, kept word for word. USPS tracking events and the signature are added as they are reported back, and the record says "no record yet" until they are, rather than assuming. Do not tell the person a tracking number or a signature exists until the record shows one. A one-page letter is $12.97 in total with USPS tracking, or $15.97 with the Electronic Return Receipt, which is the default, or $24.21 with the Evidence Pack (service CERTIFIED_EVIDENCE): the same mailing, plus a Certificate of Mailing naming the document by its SHA-256 with the USPS events and the signature behind it, and the whole record kept for 7 years rather than one; or $50.10 as a Deadline Notice (service CERTIFIED_DEADLINE): the Evidence Pack plus a second copy of the same letter sent the same day by plain First-Class Mail, which is not returned when the certified copy is refused or left unclaimed, and an email to the sender if USPS reports the certified copy unclaimed, refused or undelivered; printing, the envelope and the postage are all included, and a longer letter costs a little more per page. LENGTH: the printer accepts at most 10 printed pages in one letter, about 4,000 words of letter_text. Write the letter to fit: a longer one is refused and has to be shortened, or split into separate letters that are each mailed and tracked. U.S. destinations. WHAT COMES BACK: a link the person opens to see that exact document, the recipient, the service and the exact total, with no sign-in step in the way; they pay on that page, by card, and only then is anything printed or mailed. Give it the document ONE of four ways: (1) letter_text — the COMPLETE final letter you wrote (salutation through closing), laid out as a business letter with the addresses and date from the other fields, and still editable by the person; (2) document_text — the full text of a document that is ALREADY FINISHED and must not be re-formatted as a letter: a document the person supplied, text you read out of a PDF or an attachment, a filled-in form, a notice. It is printed exactly as written, with nothing added — no return address, no date line, no signature block. Use this whenever the document is not a letter you have just composed; (3) document_base64 — the bytes of a finished PDF, only when you can actually read the file (up to 4 MB), kept byte for byte; (4) person_has_pdf: true — the person attaches the PDF themselves on the review page, everything else prefilled. ADDRESSES: the simplest way is recipient_address_block (and sender_address_block) — paste the name and address exactly as they appear in the letter, one part per line, and Piloxa reads them into the right fields; naming the fields yourself always wins over the block. Anything still missing is asked of the person on the review page and does not stop this call. When the letter asks for an answer by a date, Piloxa emails the sender once, the day after that date, with the date USPS delivered it and the next step if nobody answered, at no extra charge. This tool NEVER mails anything and NEVER charges anyone.

Input Schema

TableJSON Schema

Name	Required	Description
`city`	No
`state`	No	Two-letter U.S. state code.
`service`	No	Pick by what rides on the letter. CERTIFIED_ERR ($15.97 for one page) is the DEFAULT for an ordinary letter: Certified Mail with the Electronic Return Receipt, the record of who signed, kept when USPS reports it back. CERTIFIED ($12.97) is Certified Mail with tracking but no record of who signed; use it only when the person asks for the cheapest way. CERTIFIED_EVIDENCE ($24.21) is CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing, and the record kept for 7 years instead of one; use it when proof of exactly what was sent may be needed later in a dispute - a debt validation notice, a notice to cure, a proof of loss, a demand before suing. CERTIFIED_DEADLINE ($50.10) is CERTIFIED_EVIDENCE plus a second copy by First-Class Mail the same day and a warning email if the certified copy goes unclaimed; use it when a missed or refused notice would cost a lien, a contract remedy or a claim - a pre-lien or preliminary notice, a notice with a statutory deadline. When this field is left out and the letter reads as such a notice, Piloxa selects CERTIFIED_DEADLINE on the review page and says so in its answer; the person can switch it back there. Whichever you pick, say its price to the person before they open the link.
`subject`	No	The "Re:" line of the letter, in a few words.
`reply_by`	No	Optional: the date, as YYYY-MM-DD, by which the letter asks the recipient to answer, pay or act. Leave it out and Piloxa reads it from the letter ("within 30 days of receipt", "no later than October 15, 2026"). The day after that date Piloxa emails the sender, once, with the date USPS delivered the letter and the next step if nobody answered, at no charge.
`page_count`	No	Only with person_has_pdf: number of pages in the PDF the person will attach, used for the price estimate.
`letter_date`	No	Date to print on the letter, e.g. "September 5, 2026". Defaults to today.
`letter_text`	No	The complete, final letter body exactly as it should print: salutation, paragraphs separated by blank lines, and closing. Do not include the addresses or date; they are laid out from the other fields. Up to 60,000 characters. It must fit in 10 printed pages, about 4,000 words.
`postal_code`	No	Five-digit ZIP code.
`sender_city`	No
`sender_name`	No	Name of the person sending the letter (printed as the return address and used for the envelope).
`sender_state`	No	Two-letter U.S. state code.
`address_line1`	No	Street address of the recipient.
`address_line2`	No	Suite, unit or floor.
`document_text`	No	The COMPLETE text of a document that is already finished, printed exactly as written: no return address, no date line, no "Re:" line and no signature block are added, and line breaks and indentation are kept. This is the right field for a document the person gave you, for text you read out of a PDF or an attachment, for a filled-in form or a notice — anything you did not compose as a letter in this conversation. Include every word that must print, the addresses and signature line included if the document carries them. Up to 60,000 characters. Mutually exclusive with letter_text and document_base64.
`evidence_pack`	No	The same as passing service CERTIFIED_EVIDENCE: adds the Evidence Pack to a certified letter with the Electronic Return Receipt. One page is $24.21 in total instead of $15.97.
`person_has_pdf`	No	Only when the person already has a finished PDF that neither you nor they can give you the text of, and they will attach it on the review page themselves. Set true to prepare without letter_text, document_text or document_base64. Prefer document_text whenever you can read the document at all: it saves the person an upload.
`recipient_name`	No	Name of the person or company receiving the letter.
`sender_company`	No	Sender company or entity, if any.
`signature_name`	No	Name printed under the closing.
`document_base64`	No	The finished PDF, base64-encoded (standard or URL-safe alphabet), up to 4 MB decoded. Use ONLY when you have read the actual file bytes; a filename or an attachment reference is not a document. Mutually exclusive with letter_text and document_text. The file is kept exactly as sent.
`document_sha256`	No	Optional with document_base64: the SHA-256 (hex) of the PDF bytes. If given and it does not match what arrived, the call is refused rather than preparing the wrong file.
`document_filename`	No	With document_base64: the original file name, e.g. "Demand letter.pdf".
`recipient_company`	No	Company name, if the letter goes to an organization.
`sender_postal_code`	No	Five-digit ZIP code.
`document_description`	No	What the document is, in a few words.
`sender_address_block`	No	The sender exactly as it should appear as the return address, one part per line. Read the same way as recipient_address_block. This is where a returned envelope goes back to.
`sender_address_line1`	No	Sender street address.
`sender_address_line2`	No
`recipient_address_block`	No	The recipient exactly as addressed in the letter, one part per line, e.g. "Acme Property Management LLC\nAttn: Jane Doe\n1234 Wilshire Blvd, Suite 500\nLos Angeles, CA 90017". Piloxa reads the name, company, street, suite, city, state and ZIP out of it. Use this when you have the address as written and do not want to split it up yourself; any field you also name explicitly wins over it.

Output Schema

TableJSON Schema

Name	Required	Description
`mailed`	Yes	Always false here: this tool never mails.
`charged`	Yes	Always false here: this tool never charges.
`service`	No
`recipient`	No	The recipient as Piloxa read it, including anything parsed out of recipient_address_block. Check it against the letter and say it back to the person.
`page_count`	No
`approval_url`	Yes	Link the person opens to review, pay and authorize.
`document_kind`	No	Which way the document arrived, and so what the person will see on the page.
`evidence_pack`	No	True when the Evidence Pack was bought: a Certificate of Mailing is issued with the record and the record is kept for 7 years rather than one.
`ready_to_mail`	No	True when nothing is missing: the person only has to read it, pay and authorize.
`document_sha256`	No	SHA-256 of the rendered PDF, when document_rendered is true.
`estimated_total`	No	The same total, formatted for a person, e.g. "$16.17".
`upload_required`	No	True when the person still has to attach the PDF on the review page.
`account_required`	No	Always false: the person needs no account to open the link and read the letter, and none is created by this call.
`document_received`	No	True when document_base64 arrived intact and is the PDF the person will review; false otherwise.
`document_rendered`	No	True when letter_text or document_text was laid out into the PDF the person will review; false otherwise.
`missing_for_mailing`	No	What is still needed before this can be mailed, in plain words. Empty when nothing is missing. Ask the person for these now.
`recommended_because`	No	What in the letter led to that recommendation.
`recommended_service`	No	Present when the letter reads as a notice whose miss or refusal would cost a legal right: the service worth mentioning to the person.
`estimated_total_cents`	No
`requires_human_approval`	Yes
`estimated_service_fee_cents`	No
`estimated_provider_cost_cents`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 26, 2026

addedInput schema / properties / reply_by

Added value: +{
+  "description": "Optional: the date, as YYYY-MM-DD, by which the letter asks the recipient to answer, pay or act. Leave it out and Piloxa reads it from the letter (\"within 30 days of receipt\", \"no later than October 15, 2026\"). The day after that date Piloxa emails the sender, once, with the date USPS delivered the letter and the next step if nobody answered, at no charge.",
+  "type": "string"
+}

Changed2 schema fields changedSep 25, 2026

changedInput schema / properties / evidence_pack / description

Previous value: -"The same as passing service CERTIFIED_EVIDENCE: adds the Evidence Pack to a certified letter with the Electronic Return Receipt. One page is $24.41 in total instead of $16.17."New value: +"The same as passing service CERTIFIED_EVIDENCE: adds the Evidence Pack to a certified letter with the Electronic Return Receipt. One page is $24.21 in total instead of $15.97."

changedInput schema / properties / service / description

Previous value: -"Pick by what rides on the letter. CERTIFIED_ERR ($16.17 for one page) is the DEFAULT for an ordinary letter: Certified Mail with the Electronic Return Receipt, the record of who signed, kept when USPS reports it back. CERTIFIED ($13.18) is Certified Mail with tracking but no record of who signed; use it only when the person asks for the cheapest way. CERTIFIED_EVIDENCE ($24.41) is CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing, and the record kept for 7 years instead of one; use it when proof of exactly what was sent may be needed later in a dispute - a debt validation notice, a notice to cure, a proof of loss, a demand before suing. CERTIFIED_DEADLINE ($50.10) is CERTIFIED_EVIDENCE plus a second copy by First-Class Mail the same day and a warning email if the certified copy goes unclaimed; use it when a missed or refused notice would cost a lien, a contract remedy or a claim - a pre-lien or preliminary notice, a notice with a statutory deadline. When this field is left out and the letter reads as such a notice, Piloxa selects CERTIFIED_DEADLINE on the review page and says so in its answer; the person can switch it back there. Whichever you pick, say its price to the person before they open the link."New value: +"Pick by what rides on the letter. CERTIFIED_ERR ($15.97 for one page) is the DEFAULT for an ordinary letter: Certified Mail with the Electronic Return Receipt, the record of who signed, kept when USPS reports it back. CERTIFIED ($12.97) is Certified Mail with tracking but no record of who signed; use it only when the person asks for the cheapest way. CERTIFIED_EVIDENCE ($24.21) is CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing, and the record kept for 7 years instead of one; use it when proof of exactly what was sent may be needed later in a dispute - a debt validation notice, a notice to cure, a proof of loss, a demand before suing. CERTIFIED_DEADLINE ($50.10) is CERTIFIED_EVIDENCE plus a second copy by First-Class Mail the same day and a warning email if the certified copy goes unclaimed; use it when a missed or refused notice would cost a lien, a contract remedy or a claim - a pre-lien or preliminary notice, a notice with a statutory deadline. When this field is left out and the letter reads as such a notice, Piloxa selects CERTIFIED_DEADLINE on the review page and says so in its answer; the person can switch it back there. Whichever you pick, say its price to the person before they open the link."

Changed1 schema field changedSep 25, 2026

changedInput schema / properties / letter_text / description

Previous value: -"The complete, final letter body exactly as it should print: salutation, paragraphs separated by blank lines, and closing. Do not include the addresses or date; they are laid out from the other fields. Up to 60,000 characters. It must fit in 5 printed pages, about 2,000 words."New value: +"The complete, final letter body exactly as it should print: salutation, paragraphs separated by blank lines, and closing. Do not include the addresses or date; they are laid out from the other fields. Up to 60,000 characters. It must fit in 10 printed pages, about 4,000 words."

Changed2 schema fields changedSep 25, 2026

changedInput schema / properties / letter_text / description

Previous value: -"The complete, final letter body exactly as it should print: salutation, paragraphs separated by blank lines, and closing. Do not include the addresses or date; they are laid out from the other fields. Up to 60,000 characters."New value: +"The complete, final letter body exactly as it should print: salutation, paragraphs separated by blank lines, and closing. Do not include the addresses or date; they are laid out from the other fields. Up to 60,000 characters. It must fit in 5 printed pages, about 2,000 words."

changedInput schema / properties / service / description

Previous value: -"CERTIFIED_ERR adds the Electronic Return Receipt (the record of who signed, kept when USPS reports it back) and is the DEFAULT for an ordinary letter. CERTIFIED is certified mail with tracking but no record of who signed. CERTIFIED_EVIDENCE is the same mailing as CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing, and the record kept for 7 years instead of one. Choose it when the letter is a statutory or contractual notice whose proof may be needed in a dispute later - a pre-lien or preliminary notice, a debt validation notice, a notice to cure, a notice of intent to sue, a proof of loss - and say the price back to the person before they pay. CERTIFIED_DEADLINE ($50.10 for one page) is CERTIFIED_EVIDENCE plus a second copy by First-Class Mail the same day and a warning email if the certified copy goes unclaimed: choose it when a missed or refused notice would cost a lien, a contract remedy or a claim. When this field is left out and the letter reads as such a notice, Piloxa selects CERTIFIED_DEADLINE on the review page and says so in its answer; the person can switch it back there."New value: +"Pick by what rides on the letter. CERTIFIED_ERR ($16.17 for one page) is the DEFAULT for an ordinary letter: Certified Mail with the Electronic Return Receipt, the record of who signed, kept when USPS reports it back. CERTIFIED ($13.18) is Certified Mail with tracking but no record of who signed; use it only when the person asks for the cheapest way. CERTIFIED_EVIDENCE ($24.41) is CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing, and the record kept for 7 years instead of one; use it when proof of exactly what was sent may be needed later in a dispute - a debt validation notice, a notice to cure, a proof of loss, a demand before suing. CERTIFIED_DEADLINE ($50.10) is CERTIFIED_EVIDENCE plus a second copy by First-Class Mail the same day and a warning email if the certified copy goes unclaimed; use it when a missed or refused notice would cost a lien, a contract remedy or a claim - a pre-lien or preliminary notice, a notice with a statutory deadline. When this field is left out and the letter reads as such a notice, Piloxa selects CERTIFIED_DEADLINE on the review page and says so in its answer; the person can switch it back there. Whichever you pick, say its price to the person before they open the link."

Changed5 schema fields changedSep 24, 2026

changedInput schema / properties / service / description

Previous value: -"CERTIFIED_ERR adds the Electronic Return Receipt (the record of who signed, kept when USPS reports it back) and is the DEFAULT: leave this out unless the person has said they do not want the signature record. CERTIFIED is certified mail with tracking but no record of who signed. CERTIFIED_EVIDENCE is the same mailing as CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing, and the record kept for 7 years instead of one. Choose it when the letter is a statutory or contractual notice whose proof may be needed in a dispute later - a pre-lien or preliminary notice, a debt validation notice, a notice to cure, a notice of intent to sue, a proof of loss - and say the price back to the person before they pay."New value: +"CERTIFIED_ERR adds the Electronic Return Receipt (the record of who signed, kept when USPS reports it back) and is the DEFAULT for an ordinary letter. CERTIFIED is certified mail with tracking but no record of who signed. CERTIFIED_EVIDENCE is the same mailing as CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing, and the record kept for 7 years instead of one. Choose it when the letter is a statutory or contractual notice whose proof may be needed in a dispute later - a pre-lien or preliminary notice, a debt validation notice, a notice to cure, a notice of intent to sue, a proof of loss - and say the price back to the person before they pay. CERTIFIED_DEADLINE ($50.10 for one page) is CERTIFIED_EVIDENCE plus a second copy by First-Class Mail the same day and a warning email if the certified copy goes unclaimed: choose it when a missed or refused notice would cost a lien, a contract remedy or a claim. When this field is left out and the letter reads as such a notice, Piloxa selects CERTIFIED_DEADLINE on the review page and says so in its answer; the person can switch it back there."

changedInput schema / properties / service / enum

Previous value: -[
-  "CERTIFIED",
-  "CERTIFIED_ERR",
-  "CERTIFIED_EVIDENCE"
-]New value: +[
+  "CERTIFIED",
+  "CERTIFIED_ERR",
+  "CERTIFIED_EVIDENCE",
+  "CERTIFIED_DEADLINE"
+]

addedOutput schema / properties / recommended_because

Added value: +{
+  "description": "What in the letter led to that recommendation.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / recommended_service

Added value: +{
+  "description": "Present when the letter reads as a notice whose miss or refusal would cost a legal right: the service worth mentioning to the person.",
+  "type": "string"
+}

changedOutput schema / properties / service / enum

Previous value: -[
-  "CERTIFIED",
-  "CERTIFIED_ERR",
-  "CERTIFIED_EVIDENCE"
-]New value: +[
+  "CERTIFIED",
+  "CERTIFIED_ERR",
+  "CERTIFIED_EVIDENCE",
+  "CERTIFIED_DEADLINE"
+]

Changed5 schema fields changedSep 22, 2026

addedInput schema / properties / evidence_pack

Added value: +{
+  "description": "The same as passing service CERTIFIED_EVIDENCE: adds the Evidence Pack to a certified letter with the Electronic Return Receipt. One page is $24.41 in total instead of $16.17.",
+  "type": "boolean"
+}

changedInput schema / properties / service / description

Previous value: -"CERTIFIED_ERR adds the Electronic Return Receipt (the record of who signed, kept when USPS reports it back) and is the DEFAULT: leave this out unless the person has said they do not want the signature record. CERTIFIED is certified mail with tracking but no record of who signed."New value: +"CERTIFIED_ERR adds the Electronic Return Receipt (the record of who signed, kept when USPS reports it back) and is the DEFAULT: leave this out unless the person has said they do not want the signature record. CERTIFIED is certified mail with tracking but no record of who signed. CERTIFIED_EVIDENCE is the same mailing as CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing, and the record kept for 7 years instead of one. Choose it when the letter is a statutory or contractual notice whose proof may be needed in a dispute later - a pre-lien or preliminary notice, a debt validation notice, a notice to cure, a notice of intent to sue, a proof of loss - and say the price back to the person before they pay."

changedInput schema / properties / service / enum

Previous value: -[
-  "CERTIFIED",
-  "CERTIFIED_ERR"
-]New value: +[
+  "CERTIFIED",
+  "CERTIFIED_ERR",
+  "CERTIFIED_EVIDENCE"
+]

addedOutput schema / properties / evidence_pack

Added value: +{
+  "description": "True when the Evidence Pack was bought: a Certificate of Mailing is issued with the record and the record is kept for 7 years rather than one.",
+  "type": "boolean"
+}

changedOutput schema / properties / service / enum

Previous value: -[
-  "CERTIFIED",
-  "CERTIFIED_ERR"
-]New value: +[
+  "CERTIFIED",
+  "CERTIFIED_ERR",
+  "CERTIFIED_EVIDENCE"
+]

Changed1 schema field changedSep 19, 2026

changedInput schema / properties / service / description

Previous value: -"CERTIFIED_ERR adds the Electronic Return Receipt (proof of who signed) and is the DEFAULT: leave this out unless the person has said they do not want the signature record. CERTIFIED is certified mail with tracking but no record of who signed."New value: +"CERTIFIED_ERR adds the Electronic Return Receipt (the record of who signed, kept when USPS reports it back) and is the DEFAULT: leave this out unless the person has said they do not want the signature record. CERTIFIED is certified mail with tracking but no record of who signed."

Changed1 schema field changedSep 17, 2026

changedInput schema / properties / service / description

Previous value: -"CERTIFIED_ERR adds the Electronic Return Receipt (proof of who signed)."New value: +"CERTIFIED_ERR adds the Electronic Return Receipt (proof of who signed) and is the DEFAULT: leave this out unless the person has said they do not want the signature record. CERTIFIED is certified mail with tracking but no record of who signed."

Changed13 schema fields changedSep 13, 2026

changedInput schema / properties / document_base64 / description

Previous value: -"The finished PDF, base64-encoded (standard or URL-safe alphabet), up to 4 MB decoded. Use ONLY when you have read the actual file bytes; a filename or an attachment reference is not a document. Mutually exclusive with letter_text. The file is kept exactly as sent."New value: +"The finished PDF, base64-encoded (standard or URL-safe alphabet), up to 4 MB decoded. Use ONLY when you have read the actual file bytes; a filename or an attachment reference is not a document. Mutually exclusive with letter_text and document_text. The file is kept exactly as sent."

addedInput schema / properties / document_text

Added value: +{
+  "description": "The COMPLETE text of a document that is already finished, printed exactly as written: no return address, no date line, no \"Re:\" line and no signature block are added, and line breaks and indentation are kept. This is the right field for a document the person gave you, for text you read out of a PDF or an attachment, for a filled-in form or a notice — anything you did not compose as a letter in this conversation. Include every word that must print, the addresses and signature line included if the document carries them. Up to 60,000 characters. Mutually exclusive with letter_text and document_base64.",
+  "type": "string"
+}

changedInput schema / properties / person_has_pdf / description

Previous value: -"Only when the person already has a finished PDF that you cannot read and they will attach it on the review page themselves. Set true to prepare without letter_text or document_base64."New value: +"Only when the person already has a finished PDF that neither you nor they can give you the text of, and they will attach it on the review page themselves. Set true to prepare without letter_text, document_text or document_base64. Prefer document_text whenever you can read the document at all: it saves the person an upload."

addedInput schema / properties / recipient_address_block

Added value: +{
+  "description": "The recipient exactly as addressed in the letter, one part per line, e.g. \"Acme Property Management LLC\\nAttn: Jane Doe\\n1234 Wilshire Blvd, Suite 500\\nLos Angeles, CA 90017\". Piloxa reads the name, company, street, suite, city, state and ZIP out of it. Use this when you have the address as written and do not want to split it up yourself; any field you also name explicitly wins over it.",
+  "type": "string"
+}

addedInput schema / properties / sender_address_block

Added value: +{
+  "description": "The sender exactly as it should appear as the return address, one part per line. Read the same way as recipient_address_block. This is where a returned envelope goes back to.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "recipient_name"
-]New value: +[]

addedOutput schema / properties / account_required

Added value: +{
+  "description": "Always false: the person needs no account to open the link and read the letter, and none is created by this call.",
+  "type": "boolean"
+}

addedOutput schema / properties / document_kind

Added value: +{
+  "description": "Which way the document arrived, and so what the person will see on the page.",
+  "enum": [
+    "letter_text",
+    "document_text",
+    "pdf_bytes",
+    "person_will_attach"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / document_rendered / description

Previous value: -"True when letter_text was rendered into the PDF the person will review; false otherwise."New value: +"True when letter_text or document_text was laid out into the PDF the person will review; false otherwise."

addedOutput schema / properties / estimated_total

Added value: +{
+  "description": "The same total, formatted for a person, e.g. \"$16.17\".",
+  "type": "string"
+}

addedOutput schema / properties / missing_for_mailing

Added value: +{
+  "description": "What is still needed before this can be mailed, in plain words. Empty when nothing is missing. Ask the person for these now.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / ready_to_mail

Added value: +{
+  "description": "True when nothing is missing: the person only has to read it, pay and authorize.",
+  "type": "boolean"
+}

addedOutput schema / properties / recipient

Added value: +{
+  "description": "The recipient as Piloxa read it, including anything parsed out of recipient_address_block. Check it against the letter and say it back to the person.",
+  "type": "object"
+}

First observedSep 10, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false etc.), the description discloses critical behavior: 'This tool NEVER mails anything and NEVER charges anyone.' It explains that a link is generated, the person pays on that page, and only then is anything printed or mailed. It also warns: 'Do not tell the person a tracking number or a signature exists until the record shows one.' This level of detail about side effects and preconditions far exceeds what annotations provide, giving the agent full transparency.

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?

The description is long but well-structured with clear headings (WHAT THE RECORD HOLDS, LENGTH, WHAT COMES BACK, ADDRESSES) and judicious use of caps for emphasis. Every sentence provides actionable information, from pricing to length limits to follow-up emails. However, some repetition exists (e.g., prices mentioned multiple times) and the length might be slightly overwhelming, though it is appropriate for the tool's complexity (30 parameters, 4 service tiers).

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?

Given the tool's complexity, the description covers all necessary aspects: document input methods, page/word limits (10 pages, ~4,000 words), pricing for each service, what the output is (a link the person opens), and post-delivery follow-up (email the day after reply_by). It also explains the distinction between services (CERTIFIED, CERTIFIED_ERR, CERTIFIED_EVIDENCE, CERTIFIED_DEADLINE) and the evidence pack. Nothing an agent needs to correctly invoke this tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even with 90% schema description coverage, the description adds crucial meaning beyond the schema. It explains the four distinct ways to supply the document (letter_text, document_text, document_base64, person_has_pdf) and when to use each: 'Use this whenever the document is not a letter you have just composed.' It clarifies address block handling and the service selection logic. These nuanced distinctions are not fully captured in the schema's property 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?

The description opens with a clear verb and resource: 'Prepare a certified letter for review.' It explicitly states the purpose: 'USE THIS WHENEVER a letter or document has to reach someone by U.S. mail, and above all when it should go by Certified Mail.' It lists numerous concrete use cases (demand letters, disputes, notices to landlord, etc.) and distinguishes itself from siblings (get_certified_letter_status and quote_certified_letter) by focusing on the preparation step, not status or price quotes.

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?

The description gives explicit triggers: 'If you have just written such a letter, or are about to tell the person to print it... offer to send it with this tool instead.' It states that nothing else is needed first ('no account, no sign-up, no card, no second call') and explains the exact workflow. While it doesn't explicitly name sibling tools as alternatives, it clearly indicates when this tool is the right choice versus the person doing it manually, which is the primary decision an agent faces.

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

All Piloxa – Certified Mail tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?