{
  "$defs": {
    "address": {
      "description": "Postal address. Required: addressLine1, city, countryCode.",
      "properties": {
        "addressLine1": {
          "type": "string"
        },
        "addressLine2": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "companyName": {
          "type": "string"
        },
        "countryCode": {
          "enum": [
            "US",
            "CA"
          ],
          "type": "string"
        },
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "postalOrZip": {
          "type": "string"
        },
        "provinceOrState": {
          "type": "string"
        }
      },
      "required": [
        "addressLine1",
        "city",
        "countryCode"
      ],
      "type": "object"
    }
  },
  "description": "Agent-native print-and-mail for real, physical letters (US + Canada). No signup, no API key, no card on file. Payment is one Stripe Checkout Session per letter; fulfilment starts only after payment succeeds. Shipping labels are COMING SOON and not available. Base path /v1 on the host assigned during private testing.",
  "rules": [
    "State the exact quoted price and get explicit user approval BEFORE calling create_letter_job.",
    "Fresh UUID idempotency_key per confirmed action; reuse it on retry.",
    "Letter bodies are private: summarize, never repeat verbatim outside the task.",
    "Never ask the user for card details; payment uses the returned checkout_url.",
    "Shipping labels are coming soon \u2014 do not offer them."
  ],
  "service": "LetterAgent",
  "statuses": {
    "job": [
      "awaiting_payment",
      "paid",
      "fulfilled",
      "failed"
    ],
    "mail": {
      "cancelled": "cancelled",
      "completed": "most likely delivered (not confirmed)",
      "printing": "printing",
      "processed_for_delivery": "processed for delivery",
      "ready": "in the print queue"
    }
  },
  "tools": [
    {
      "description": "Get the exact final price for a letter before asking the user to approve it. The quote's country must match the destination address country.",
      "http": {
        "method": "POST",
        "path": "/v1/quotes"
      },
      "inputSchema": {
        "properties": {
          "color": {
            "default": false,
            "description": "True for colour printing, false for black-and-white.",
            "type": "boolean"
          },
          "country": {
            "description": "Destination country. Must match the recipient address countryCode.",
            "enum": [
              "US",
              "CA"
            ],
            "type": "string"
          },
          "pages": {
            "default": 1,
            "description": "Number of letter pages.",
            "minimum": 1,
            "type": "integer"
          },
          "registered": {
            "type": "boolean",
            "default": false,
            "description": "True for registered mail (US certified with tracking; CA registered with signature)."
          }
        },
        "required": [
          "country"
        ],
        "type": "object"
      },
      "name": "quote_letter",
      "outputExample": {
        "amount_cents": 615,
        "color": false,
        "country": "CA",
        "currency": "CAD",
        "pages": 1,
        "quote_id": "q_9f3c1a2b4d5e6f70",
        "registered": false
      }
    },
    {
      "description": "Create a letter job ONLY after the user explicitly approves the exact quoted price. Returns a one-time Stripe Checkout URL to hand to the user. Generate a fresh UUID idempotency_key per confirmed action; retrying with the same key returns the original job (HTTP 200) instead of creating a duplicate.",
      "http": {
        "method": "POST",
        "path": "/v1/jobs"
      },
      "inputSchema": {
        "properties": {
          "idempotency_key": {
            "description": "Fresh UUID per user-confirmed action. Reuse it when retrying the same action.",
            "type": "string"
          },
          "letter": {
            "properties": {
              "from": {
                "$ref": "#/$defs/address"
              },
              "html": {
                "description": "Full HTML of the letter body. Exactly one of html / pdf_url is required.",
                "type": "string"
              },
              "pdf_url": {
                "description": "URL of a PDF of the letter. Exactly one of html / pdf_url is required.",
                "format": "uri",
                "type": "string"
              },
              "to": {
                "$ref": "#/$defs/address"
              }
            },
            "required": [
              "to",
              "from"
            ],
            "type": "object"
          },
          "quote_id": {
            "description": "quote_id from quote_letter. Quotes are short-lived.",
            "type": "string"
          }
        },
        "required": [
          "quote_id",
          "letter"
        ],
        "type": "object"
      },
      "name": "create_letter_job",
      "outputExample": {
        "amount": "C$6.15",
        "amount_cents": 615,
        "checkout_url": "https://checkout.stripe.com/pay/cs_test_...",
        "currency": "CAD",
        "job_id": "job_a1b2c3d4e5f60718",
        "payment_mode": "real",
        "status": "awaiting_payment"
      }
    },
    {
      "description": "Check a letter job's status and live mail status. mail_status is only present once the job is fulfilled. 'completed' means most likely delivered, never confirmed delivery.",
      "http": {
        "method": "GET",
        "path": "/v1/jobs/{job_id}"
      },
      "inputSchema": {
        "properties": {
          "job_id": {
            "description": "job_id from create_letter_job, e.g. job_a1b2c3d4e5f60718.",
            "type": "string"
          }
        },
        "required": [
          "job_id"
        ],
        "type": "object"
      },
      "name": "get_job_status",
      "outputExample": {
        "amount": "C$6.15",
        "amount_cents": 615,
        "currency": "CAD",
        "error": null,
        "job_id": "job_a1b2c3d4e5f60718",
        "mail_status": "ready \u2014 in the print queue",
        "letter_id": "letter_v3cwk7Nwm13XRGHwkSzSsE",
        "status": "fulfilled"
      }
    }
  ]
}