Agent Letter Desk

Grußkarte vorbereiten (kostenlose Vorschau)

prepare_card

Use this when the user wants to mail a greeting card to people in the US. Give the design_id of the uploaded picture or a short front_text, the message and 1 to 20 recipients, each with an optional greeting name and message. For more recipients, call it again with batch_id (at most 100 cards in a batch). Ask the user for the date of the occasion, if it has one. Give it as occasion_date. Returns the batch, the price, each card and the notes. Nothing is mailed or charged. Do not use it for e-mail or e-cards.

Input Schema

Name	Required	Description
`message`	No	Required, unless each recipient has its own message. The message inside the card, written with the user. Use {first_name} for the greeting name of each recipient, for example "Dear {first_name},". No other field. It must fit the card: see message.max_chars in get_card_options. Always end the message with the closing and the name of the sender, as the user signs. Put the closing and the name on two lines. For example: "Love," and then "Tom". Write the name as text, not as a field. Put the greeting, each paragraph, the closing and the name on separate lines. Use a real line break between them. In English, start each paragraph with a capital letter. The card sets each part in its own style. No emojis. The card font cannot print them.
`batch_id`	No	Optional. The batch_id from an earlier prepare_card. Use it to add up to 20 more recipients to that card batch. Do not use it after send_card or after the user ordered the batch. Give the same design_id or front_text, front_style and sender_address_id. The batch then gets a new batch_sha256 and a new total. The user must approve the whole batch again.
`language`	No	Give the language of the conversation, for example en or de. The upload page and the order page use this language. Without it, the pages use the language of the account.
`design_id`	No	For a picture front: the design_id of the chosen draft from create_card_picture, or of the user's own picture from the upload link. Give design_id or front_text, not both.
`front_text`	No	A short text for the front, for example "Merry Christmas". Use it when you cannot make a picture. At most 40 characters on 1 to 3 lines. No fields. No emojis. The card font cannot print them. Give design_id or front_text, not both.
`recipients`	Yes	1 to 20 recipients in the United States. Each gets the same card. A recipient without its own message gets message.
`reprint_of`	No	Optional. Use it only when get_letter_status or list_letters shows resend_offer with state available for a card, or when the user has our e-mail about a free reprint. Give the letter_id or the Card ID of that card (for example 3F2A-9C1B-77D0). Give one recipient: the same recipient as on that card. Give the same sender_address_id. Do not give batch_id. Write the message with the user again. The price is 0.
`front_style`	No	Optional, only with front_text. "classic": Off-white card with dark green text. "winter": Deep blue card with off-white text. Default: "classic".
`occasion_date`	No	Optional. The date of the occasion as YYYY-MM-DD, for example 2026-12-25. One date for the batch. We compare it with the latest delivery day and say if the card arrives in time. Leave it out for a card after the occasion. With batch_id, leave it out to keep the date of the batch.
`sender_address_id`	No	Optional. A saved address from get_account for the sender. A US address is the return address. Default: the default address.

Output Schema

Name	Required	Description	Default
`cards`	Yes
`price`	Yes
`status`	Yes
`batch_id`	Yes
`card_count`	Yes
`batch_sha256`	Yes
`transaction_state`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations mark this as non-read-only but non-destructive, and the description supplies the crucial context the annotations cannot: 'Nothing is mailed or charged' (a free preview that creates a batch) and that a re-batched call produces a new batch_sha256 requiring re-approval. These are exactly the behavioral traits an agent needs before invoking a mutating-but-not-finalizing tool.

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?

A single front-loaded paragraph: use case first, then inputs, then return values, then the exclusion. It is dense but every sentence carries distinct information (returns, nothing charged, e-card exclusion). Minor room to tighten the input enumeration since the schema covers it.

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?

Covers what it returns ('the batch, the price, each card and the notes'), the no-charge guarantee, the batch-growth path, and the negative scope, and an output schema exists to carry return structure. Nothing an agent needs to call it correctly is missing.

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% and already documents every field in depth, so the baseline is low. The description still adds meaning beyond the schema by stating the batch_id re-call workflow and the 'at most 100 cards in a batch' ceiling, which the schema does not state, plus the design_id-vs-front_text either/or.

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 condition-of-use verb phrase ('mail a greeting card to people in the US') and names the resource and scope. It explicitly excludes e-mail and e-cards, which cleanly separates it from send_card and prepare_letter siblings without opening either 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?

Gives explicit when-to-use ('when the user wants to mail a greeting card'), when-not ('Do not use it for e-mail or e-cards'), and the branching path for volume ('For more recipients, call it again with batch_id'). The schema further routes to create_card_picture, get_card_options, and get_account, so alternatives are discoverable.

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

All Agent Letter Desk 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?