Letter IRL

Change the letter's words

set_letter_words

Idempotent

Change the words of a previewed letter without previewing it again. Give the draftId from the preview, bodyText and signOff in full, as the letter previews take them, and the wordsVersion of the words being replaced, from the preview or the last change of words. The letter card can change the words too: if they changed since you saw them, nothing is changed, and the answer gives the words as they are now. The letter is laid out again in its stationery on up to three pages: a longer letter prints on both sides and is paid with Pay & Send, and a gift letter stays on one page.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "draftId": "<draftId>",
      "bodyText": "<bodyText>",
      "signOff": "<signOff>"
    },
    "name": "set_letter_words"
  }
}

Input Schema

Name	Required	Description
`draftId`	Yes	The draftId from a letter preview
`signOff`	Yes	The closing and signature in full (e.g., 'Love, Pat')
`bodyText`	Yes	The letter's body in full: it replaces the words the preview has
`wordsVersion`	No	The wordsVersion of the words this change replaces, from the preview or the last change of words. The letter card can change the words too: if they changed since, nothing is changed, and the answer gives the words as they are now

Output Schema

Name	Required	Description
`pages`	No	Present only for a letter of more than one page: the pages it prints on, both sides of the paper. No letter pack or gift letter pays for it; it is paid with Pay & Send.
`draftId`	Yes
`message`	Yes
`canSendNow`	Yes	Whether the balance or a gift letter pays for the letter as it is now: new words can change its pages, and so its price
`mailService`	No	With the terms, for a letter that is certified mail now, and for a sent letter that went by it: which service. Absent beside the delivery words: ordinary mail
`wordsVersion`	Yes	The version of the words now, for the next change of them
`deliveryClass`	No	With the terms, for a letter that is certified mail or while certified mail is offered, and for a sent letter: how it is delivered, as a new preview would say it. A card draws it on its Delivery line
`contentVersion`	No	The version of this mail as it is now: send it with the send, so what is mailed is what the person saw
`sendEligibility`	Yes
`reasonCannotSend`	No
`deliveryDisclaimer`	No	With it, the words that qualify the delivery
`contentVersionBefore`	No	The version of this mail the change was made to: for the preview card, which takes contentVersion only when this is the version it shows

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 7, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations declare non-destructive, idempotent and closed-world, and the description adds substantial context beyond them: an optimistic-concurrency rule where stale wordsVersion means nothing is changed and the current words are returned, plus re-layout consequences (up to three pages, double-sided printing paid via Pay & Send, gift letters staying on one page).

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 purpose and inputs are front-loaded and there is no filler, but the sentences are long and multi-clause, and the final layout/printing sentence, while useful, is buried at the end rather than signposted.

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 mutation with a defined output schema, the description covers what an agent needs: required inputs and their provenance, the concurrency failure mode and what the response returns in that case, and the downstream layout/payment effects. Nothing essential is missing.

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%, so each of the four parameters is already documented, including wordsVersion with the same staleness caveat. The description's 'in full, as the letter previews take them' adds only marginal formatting nuance over the schema, so baseline 3 applies.

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 and resource ('Change the words of a previewed letter') plus a scope qualifier ('without previewing it again') that distinguishes it from the preview/quote siblings. An agent can identify the operation without opening the schema.

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?

Explains the prerequisites clearly: the draftId must come from a preview, bodyText and signOff must be given in full as the previews take them, and wordsVersion must come from the preview or the last change. It implies the alternative (re-running the preview) but never names quote_and_preview_letter explicitly as a routing choice.

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

All Letter IRL 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?