Skip to main content
Glama

Create letter draft

create_letter

Use this when the user has an uploaded PDF (document_id, or upload_id from create_upload_link) and a recipient address and wants it posted by ordinary or registered mail; registered mail is international registered mail with tracking and signature on delivery; "certified" letters, Einschreiben, lettre recommandée and carta certificada mean this here (not a US certified-mail product). Creates a draft with the exact total in the user's currency. Nothing is sent or charged; call send_letter only after the user confirms. Every envelope carries our company return address, so the user's own address belongs in the document. The account's first letter needs the user's sender details, their REAL full name (no alias, nickname or pseudonym) and postal address: pass them as sender; without them (and none saved before) the call fails with SENDER_DETAILS_REQUIRED. Once the account has them, the saved details are used (sender_details "on_file"; "kept" when a different sender was passed, which is not saved): the user changes them in Settings → Your details. A US Letter PDF to a recipient outside the US, Canada and US territories needs the user's paper choice (paper_size, same price): without it the draft says paper_choice_required. Needs the user's account.

Input Schema

NameRequiredDescriptionDefault
colorNo"bw" = black and white, "color" = colour printing (costs more per page). Default "bw".bw
duplexNotrue = print on both sides of the paper (fewer sheets, so a lighter letter); false = one side only. Default false.
senderNoThe user's own sender details: their REAL full name (first and last name, not an alias, nickname or pseudonym) and postal address, any country. Optional: needed only while the account has no sender details yet; they are then checked and saved to the account. Once the account has them, the saved details are used and this is not saved (the user changes them in Settings → Your details).
envelopeNo"DL" (220×110 mm, letter folded twice), "C5" (229×162 mm, folded once) or "C4" (324×229 mm, flat). Omit to use the smallest envelope that holds the sheets (recommended); one too small for the page count is refused.
recipientYesRecipient's postal address, printed on the envelope. Ask the user for missing fields.
upload_idNoupload_id from create_upload_link, once the user has uploaded the PDF on that page. Pass document_id or upload_id.
paper_sizeNoOnly for a US Letter PDF to a recipient outside US, CA, PR, VI, GU, AS, MP (the US, Canada and US territories): "a4" = shrink to A4 (recommended), "us_letter" = keep US Letter. Ask the user; same price. Ignored otherwise (A4 PDFs print on A4, US Letter PDFs to those countries on US Letter). No default: omit until the user has chosen.
registeredNotrue = registered mail: tracking number and signature on delivery, for an extra fee (also what "certified" letters, Einschreiben, lettre recommandée and carta certificada mean here; not a US certified-mail product). false = ordinary mail. Default false.
document_idNoThe PDF to post: document_id from upload_document or compose_letter, e.g. doc_2h7k9m4q8x1v3c6b0n5p. Pass document_id or upload_id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / sender / description
      Previous value: -"The user's own sender details: their REAL full name (first and last name, not an alias, nickname or pseudonym) and postal address, any country. Optional: needed only while the account has no sender details yet; they are then checked and saved to the account, kept on record and never printed on the envelope or in the letter. Once the account has them, the saved details are used and this is not saved (the user changes them in Settings → Your details)."New value: +"The user's own sender details: their REAL full name (first and last name, not an alias, nickname or pseudonym) and postal address, any country. Optional: needed only while the account has no sender details yet; they are then checked and saved to the account. Once the account has them, the saved details are used and this is not saved (the user changes them in Settings → Your details)."
  2. Changed1 schema field changed
    • addedInput schema / properties / sender
      Added value: +{
      +  "description": "The user's own sender details: their REAL full name (first and last name, not an alias, nickname or pseudonym) and postal address, any country. Optional: needed only while the account has no sender details yet; they are then checked and saved to the account, kept on record and never printed on the envelope or in the letter. Once the account has them, the saved details are used and this is not saved (the user changes them in Settings → Your details).",
      +  "properties": {
      +    "city": {
      +      "description": "City or town, e.g. Berlin.",
      +      "maxLength": 50,
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "company": {
      +      "description": "The user's company or organisation, e.g. Example GmbH. Optional.",
      +      "maxLength": 60,
      +      "type": "string"
      +    },
      +    "country": {
      +      "description": "Country as an ISO 3166-1 alpha-2 code, e.g. DE, FR or US.",
      +      "maxLength": 2,
      +      "minLength": 2,
      +      "type": "string"
      +    },
      +    "line1": {
      +      "description": "Street and house number, or PO box, e.g. Hauptstraße 5.",
      +      "maxLength": 60,
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "line2": {
      +      "description": "Optional extra address line: c/o, apartment, floor or building, e.g. Apt 4B.",
      +      "maxLength": 60,
      +      "type": "string"
      +    },
      +    "name": {
      +      "description": "The user's full name: their REAL first and last name, not an alias, nickname or pseudonym, e.g. Anna Schmidt.",
      +      "maxLength": 60,
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "postal_code": {
      +      "description": "Postcode / ZIP code, e.g. 10115 or 94105. Required in countries that use postcodes.",
      +      "maxLength": 16,
      +      "type": "string"
      +    },
      +    "region": {
      +      "description": "State, province or region where the user's country has one in addresses, e.g. CA (California, US), ON (Ontario, CA) or Madrid (ES). Required for addresses in AE, AS, AU, BR, CA, CN, CO, CR, ES, FM, HK, HN, ID, IN, IQ, IT, JM, JP, KN, KR, KY, MH, MP, MX, NR, PF, PG, PW, RU, SO, SV, TW, US, VE, VI, VN when this block is saved as the user's sender details (an account without them yet: SENDER_DETAILS_REQUIRED, fields.region); otherwise optional.",
      +      "maxLength": 50,
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "name",
      +    "line1",
      +    "city",
      +    "country"
      +  ],
      +  "type": "object"
      +}
  3. Changed16 schema fields changed
    • addedInput schema / properties / color / description
      Added value: +"\"bw\" = black and white, \"color\" = colour printing (costs more per page). Default \"bw\"."
    • addedInput schema / properties / document_id / description
      Added value: +"The PDF to post: document_id from upload_document or compose_letter, e.g. doc_2h7k9m4q8x1v3c6b0n5p. Pass document_id or upload_id."
    • addedInput schema / properties / duplex / description
      Added value: +"true = print on both sides of the paper (fewer sheets, so a lighter letter); false = one side only. Default false."
    • addedInput schema / properties / envelope / description
      Added value: +"\"DL\" (220×110 mm, letter folded twice), \"C5\" (229×162 mm, folded once) or \"C4\" (324×229 mm, flat). Omit to use the smallest envelope that holds the sheets (recommended); one too small for the page count is refused."
    • changedInput schema / properties / paper_size / description
      Previous value: -"Only for a US Letter PDF to a recipient outside US, CA, PR, VI, GU, AS, MP (the US, Canada and US territories): \"a4\" = shrink to A4 (recommended), \"us_letter\" = keep US Letter. Ask the user; same price. Ignored otherwise (A4 PDFs print on A4, US Letter PDFs to those countries on US Letter)."New value: +"Only for a US Letter PDF to a recipient outside US, CA, PR, VI, GU, AS, MP (the US, Canada and US territories): \"a4\" = shrink to A4 (recommended), \"us_letter\" = keep US Letter. Ask the user; same price. Ignored otherwise (A4 PDFs print on A4, US Letter PDFs to those countries on US Letter). No default: omit until the user has chosen."
    • addedInput schema / properties / recipient / description
      Added value: +"Recipient's postal address, printed on the envelope. Ask the user for missing fields."
    • addedInput schema / properties / recipient / properties / city / description
      Added value: +"City or town, e.g. Berlin."
    • changedInput schema / properties / recipient / properties / company / description
      Previous value: -"Company or organisation (optional)"New value: +"Recipient's company or organisation, e.g. Example GmbH. Optional."
    • changedInput schema / properties / recipient / properties / country / description
      Previous value: -"ISO 3166-1 alpha-2 country code, e.g. DE, FR, US"New value: +"Country as an ISO 3166-1 alpha-2 code, e.g. DE, FR or US."
    • changedInput schema / properties / recipient / properties / line1 / description
      Previous value: -"Street and house number, or PO box"New value: +"Street and house number, or PO box, e.g. Hauptstraße 5."
    • changedInput schema / properties / recipient / properties / line2 / description
      Previous value: -"Additional line: c/o, apartment, building"New value: +"Optional extra address line: c/o, apartment, floor or building, e.g. Apt 4B."
    • changedInput schema / properties / recipient / properties / name / description
      Previous value: -"Recipient (person) name"New value: +"Recipient's name: a person, or a department such as Customer Service when writing to a company, e.g. Erika Mustermann."
    • changedInput schema / properties / recipient / properties / postal_code / description
      Previous value: -"Postcode / ZIP (required in most countries)"New value: +"Postcode / ZIP code, e.g. 10115 or 94105. Required in countries that use postcodes."
    • changedInput schema / properties / recipient / properties / region / description
      Previous value: -"State / province where the country uses it (e.g. US state code CA)"New value: +"State, province or region. Required for recipients in AE, AS, AU, BR, CA, CN, CO, CR, ES, FM, HK, HN, ID, IN, IQ, IT, JM, JP, KN, KR, KY, MH, MP, MX, NR, PF, PG, PW, RU, SO, SV, TW, US, VE, VI, VN (without it the draft is refused: INVALID_ADDRESS, fields.region); omit where addresses have none, e.g. DE, FR or GB. The code in US, CA, AU and BR, e.g. CA (California) or ON (Ontario); elsewhere the name or its usual abbreviation, e.g. Madrid (ES) or RM (Rome, IT)."
    • changedInput schema / properties / registered / description
      Previous value: -"Registered mail (tracking + signature on delivery)"New value: +"true = registered mail: tracking number and signature on delivery, for an extra fee (also what \"certified\" letters, Einschreiben, lettre recommandée and carta certificada mean here; not a US certified-mail product). false = ordinary mail. Default false."
    • changedInput schema / properties / upload_id / description
      Previous value: -"From create_upload_link, once the user has uploaded"New value: +"upload_id from create_upload_link, once the user has uploaded the PDF on that page. Pass document_id or upload_id."
  4. Changed1 schema field changed
    • addedInput schema / properties / paper_size
      Added value: +{
      +  "description": "Only for a US Letter PDF to a recipient outside US, CA, PR, VI, GU, AS, MP (the US, Canada and US territories): \"a4\" = shrink to A4 (recommended), \"us_letter\" = keep US Letter. Ask the user; same price. Ignored otherwise (A4 PDFs print on A4, US Letter PDFs to those countries on US Letter).",
      +  "enum": [
      +    "a4",
      +    "us_letter"
      +  ],
      +  "type": "string"
      +}
  5. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world, so the bar is lower, yet the description adds real behavior: draft-only, no charge or dispatch, the exact total quoted in user currency, and named failure modes (SENDER_DETAILS_REQUIRED, paper_choice_required, INVALID_ADDRESS, refused too-small envelope). It also explains the saved-versus-kept sender state ('on_file'/'kept'). It stops short of describing what the draft object itself returns, but with no output schema that is a minor gap rather than a serious one.

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?

Well front-loaded: the trigger condition comes first, then the draft/no-charge contract, then prerequisites and the paper-size wrinkle. It is dense rather than padded, though it is long enough that the sender-details paragraph partly duplicates schema text and could be trimmed.

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?

For a 9-parameter nested-object creation tool with no output schema, the description covers the pieces that actually cause failed calls: first-letter sender details, region-required countries, the US Letter to non-US paper choice, envelope sizing, and the confirmation handoff to send_letter. An agent can call this correctly without further discovery.

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

Parameters3/5

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

Schema description coverage is 100% and the nested sender/recipient blocks already document region rules, ISO codes and paper_size conditions, so the description mostly restates what structured data provides. It does add one genuinely non-schema insight — that every envelope carries the company return address, so the user's own address belongs in the document — which nudges it to the top of the baseline band.

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 concrete precondition (uploaded PDF plus recipient address) and a specific verb (creates a draft for posting by ordinary or registered mail), and explicitly distinguishes the act from send_letter. It also pins down the ambiguous term 'certified' versus Einschreiben/lettre recommandée, so an agent knows exactly what this tool produces.

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?

States when to use it, names the upstream alternatives (document_id from upload_document/compose_letter, or upload_id from create_upload_link), and gives an explicit when-not: nothing is sent or charged, and send_letter is the follow-up call after the user confirms. The user-facing prerequisites (sender details, paper choice) are attached to the right moments.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.