Skip to main content
Glama
Sign In

Magic Envelope

by com.magic-envelope
OverviewDiscussionsAdmin

Update a letter

update_letter

Change a letter. Only the fields you send change (lang, style… are kept). Links keep working. You may send the same object get_letter returned, including its card wrapper — it is applied. A body with no letter fields is an error, not a silent success. guests replaces the list but keeps each existing guest's id and link (matched by id, then by name); addGuests appends without touching anyone else. Image URLs are copied at full size. Text has no character limit; italic: true (or fontStyle: "italic"); custom.frame is none | rule | ornate.

Input Schema

NameRequiredDescriptionDefault
idYes
editKeyYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +{}
    • removedInput schema / properties / addGuests
      Removed value: -{
-  "description": "Guests to append; existing guests and links are untouched.",
-  "items": {
-    "properties": {
-      "name": {
-        "maxLength": 80,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "name"
-    ],
-    "type": "object"
-  },
-  "maxItems": 1000,
-  "type": "array"
-}
    • removedInput schema / properties / blocks
      Removed value: -{
-  "description": "Letter blocks, top to bottom. Replaces all blocks. Use {name} in text to address each guest.",
-  "items": {
-    "oneOf": [
-      {
-        "properties": {
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "size": {
-            "default": "xl",
-            "enum": [
-              "md",
-              "lg",
-              "xl"
-            ],
-            "type": "string"
-          },
-          "text": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "type": {
-            "const": "heading",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "text"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "align": {
-            "default": "center",
-            "enum": [
-              "left",
-              "center"
-            ],
-            "type": "string"
-          },
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "text": {
-            "maxLength": 4000,
-            "type": "string"
-          },
-          "type": {
-            "const": "text",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "text"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "shape": {
-            "default": "wide",
-            "enum": [
-              "wide",
-              "square",
-              "round"
-            ],
-            "type": "string"
-          },
-          "src": {
-            "maxLength": 2048,
-            "type": "string"
-          },
-          "type": {
-            "const": "image",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "src"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "end": {
-            "maxLength": 40,
-            "type": "string"
-          },
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "interactive": {
-            "default": true,
-            "type": "boolean"
-          },
-          "start": {
-            "maxLength": 40,
-            "type": "string"
-          },
-          "title": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "type": {
-            "const": "date",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "start"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "address": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "interactive": {
-            "default": true,
-            "type": "boolean"
-          },
-          "name": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "type": {
-            "const": "place",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "name",
-          "address"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "to": {
-            "default": "",
-            "maxLength": 40,
-            "type": "string"
-          },
-          "type": {
-            "const": "countdown",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "href": {
-            "maxLength": 2048,
-            "type": "string"
-          },
-          "icon": {
-            "default": "link",
-            "enum": [
-              "link",
-              "gift",
-              "music",
-              "video",
-              "map",
-              "camera"
-            ],
-            "type": "string"
-          },
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "interactive": {
-            "default": true,
-            "type": "boolean"
-          },
-          "label": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "type": {
-            "const": "link",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "label",
-          "href"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "caption": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "data": {
-            "maxLength": 2048,
-            "type": "string"
-          },
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "type": {
-            "const": "qr",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "data"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "channel": {
-            "enum": [
-              "whatsapp",
-              "sms",
-              "email"
-            ],
-            "type": "string"
-          },
-          "contacts": {
-            "properties": {
-              "email": {
-                "default": "",
-                "maxLength": 200,
-                "type": "string"
-              },
-              "sms": {
-                "default": "",
-                "maxLength": 200,
-                "type": "string"
-              },
-              "whatsapp": {
-                "default": "",
-                "maxLength": 200,
-                "type": "string"
-              }
-            },
-            "type": "object"
-          },
-          "deadline": {
-            "maxLength": 40,
-            "type": "string"
-          },
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "interactive": {
-            "default": true,
-            "type": "boolean"
-          },
-          "type": {
-            "const": "rsvp",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "channel",
-          "contacts"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "items": {
-            "items": {
-              "properties": {
-                "time": {
-                  "maxLength": 10,
-                  "type": "string"
-                },
-                "what": {
-                  "maxLength": 200,
-                  "type": "string"
-                }
-              },
-              "required": [
-                "time",
-                "what"
-              ],
-              "type": "object"
-            },
-            "maxItems": 20,
-            "type": "array"
-          },
-          "type": {
-            "const": "agenda",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "items"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "board": {
-            "default": [],
-            "items": {
-              "oneOf": [
-                {
-                  "properties": {
-                    "kind": {
-                      "const": "color",
-                      "type": "string"
-                    },
-                    "value": {
-                      "pattern": "^#[0-9a-f]{6}$",
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "kind",
-                    "value"
-                  ],
-                  "type": "object"
-                },
-                {
-                  "properties": {
-                    "kind": {
-                      "const": "emoji",
-                      "type": "string"
-                    },
-                    "value": {
-                      "maxLength": 16,
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "kind",
-                    "value"
-                  ],
-                  "type": "object"
-                },
-                {
-                  "properties": {
-                    "kind": {
-                      "const": "text",
-                      "type": "string"
-                    },
-                    "value": {
-                      "maxLength": 60,
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "kind",
-                    "value"
-                  ],
-                  "type": "object"
-                },
-                {
-                  "properties": {
-                    "kind": {
-                      "const": "image",
-                      "type": "string"
-                    },
-                    "value": {
-                      "maxLength": 2048,
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "kind",
-                    "value"
-                  ],
-                  "type": "object"
-                }
-              ]
-            },
-            "maxItems": 12,
-            "type": "array"
-          },
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "text": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "type": {
-            "const": "dress",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "text"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "href": {
-            "maxLength": 2048,
-            "type": "string"
-          },
-          "iban": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "interactive": {
-            "default": true,
-            "type": "boolean"
-          },
-          "text": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "type": {
-            "const": "gift",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "text"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "text": {
-            "maxLength": 200,
-            "type": "string"
-          },
-          "type": {
-            "const": "signature",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "text"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "style": {
-            "default": "flourish",
-            "enum": [
-              "flourish",
-              "stars",
-              "line"
-            ],
-            "type": "string"
-          },
-          "type": {
-            "const": "divider",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "href": {
-            "maxLength": 2048,
-            "type": "string"
-          },
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "type": {
-            "const": "music",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "href"
-        ],
-        "type": "object"
-      },
-      {
-        "properties": {
-          "id": {
-            "maxLength": 32,
-            "minLength": 1,
-            "type": "string"
-          },
-          "stamp": {
-            "anyOf": [
-              {
-                "enum": [
-                  "love",
-                  "rose",
-                  "dove",
-                  "castle",
-                  "moon",
-                  "cake",
-                  "sunflower",
-                  "shell",
-                  "butterfly",
-                  "star",
-                  "key",
-                  "rocket",
-                  "disco",
-                  "invader"
-                ],
-                "type": "string"
-              },
-              {
-                "const": "",
-                "type": "string"
-              }
-            ]
-          },
-          "type": {
-            "const": "stamp",
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "type",
-          "stamp"
-        ],
-        "type": "object"
-      }
-    ]
-  },
-  "maxItems": 60,
-  "minItems": 1,
-  "type": "array"
-}
    • removedInput schema / properties / custom
      Removed value: -{
-  "description": "Overrides on top of the style: accent/paper/ink/envelope colours, head/body fonts",
-  "properties": {
-    "accent": {
-      "pattern": "^#[0-9a-f]{6}$",
-      "type": "string"
-    },
-    "body": {
-      "enum": [
-        "medieval",
-        "fell",
-        "playfair",
-        "kalam",
-        "inter",
-        "grotesk",
-        "monoton",
-        "righteous",
-        "pixel",
-        "vt323",
-        "cinzel",
-        "fredoka",
-        "courier",
-        "bebas"
-      ],
-      "type": "string"
-    },
-    "envelope": {
-      "pattern": "^#[0-9a-f]{6}$",
-      "type": "string"
-    },
-    "head": {
-      "enum": [
-        "medieval",
-        "fell",
-        "playfair",
-        "kalam",
-        "inter",
-        "grotesk",
-        "monoton",
-        "righteous",
-        "pixel",
-        "vt323",
-        "cinzel",
-        "fredoka",
-        "courier",
-        "bebas"
-      ],
-      "type": "string"
-    },
-    "ink": {
-      "pattern": "^#[0-9a-f]{6}$",
-      "type": "string"
-    },
-    "paper": {
-      "pattern": "^#[0-9a-f]{6}$",
-      "type": "string"
-    }
-  },
-  "type": "object"
-}
    • removedInput schema / properties / envelope
      Removed value: -{
-  "description": "Envelope slot blocks, partial like letter blocks (see catalog.envelope for each slot's block type)",
-  "properties": {
-    "blocks": {
-      "additionalProperties": {
-        "oneOf": [
-          {
-            "properties": {
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "size": {
-                "default": "xl",
-                "enum": [
-                  "md",
-                  "lg",
-                  "xl"
-                ],
-                "type": "string"
-              },
-              "text": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "type": {
-                "const": "heading",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "text"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "align": {
-                "default": "center",
-                "enum": [
-                  "left",
-                  "center"
-                ],
-                "type": "string"
-              },
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "text": {
-                "maxLength": 4000,
-                "type": "string"
-              },
-              "type": {
-                "const": "text",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "text"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "shape": {
-                "default": "wide",
-                "enum": [
-                  "wide",
-                  "square",
-                  "round"
-                ],
-                "type": "string"
-              },
-              "src": {
-                "maxLength": 2048,
-                "type": "string"
-              },
-              "type": {
-                "const": "image",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "src"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "end": {
-                "maxLength": 40,
-                "type": "string"
-              },
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "interactive": {
-                "default": true,
-                "type": "boolean"
-              },
-              "start": {
-                "maxLength": 40,
-                "type": "string"
-              },
-              "title": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "type": {
-                "const": "date",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "start"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "address": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "interactive": {
-                "default": true,
-                "type": "boolean"
-              },
-              "name": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "type": {
-                "const": "place",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "name",
-              "address"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "to": {
-                "default": "",
-                "maxLength": 40,
-                "type": "string"
-              },
-              "type": {
-                "const": "countdown",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "href": {
-                "maxLength": 2048,
-                "type": "string"
-              },
-              "icon": {
-                "default": "link",
-                "enum": [
-                  "link",
-                  "gift",
-                  "music",
-                  "video",
-                  "map",
-                  "camera"
-                ],
-                "type": "string"
-              },
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "interactive": {
-                "default": true,
-                "type": "boolean"
-              },
-              "label": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "type": {
-                "const": "link",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "label",
-              "href"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "caption": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "data": {
-                "maxLength": 2048,
-                "type": "string"
-              },
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "type": {
-                "const": "qr",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "data"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "channel": {
-                "enum": [
-                  "whatsapp",
-                  "sms",
-                  "email"
-                ],
-                "type": "string"
-              },
-              "contacts": {
-                "properties": {
-                  "email": {
-                    "default": "",
-                    "maxLength": 200,
-                    "type": "string"
-                  },
-                  "sms": {
-                    "default": "",
-                    "maxLength": 200,
-                    "type": "string"
-                  },
-                  "whatsapp": {
-                    "default": "",
-                    "maxLength": 200,
-                    "type": "string"
-                  }
-                },
-                "type": "object"
-              },
-              "deadline": {
-                "maxLength": 40,
-                "type": "string"
-              },
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "interactive": {
-                "default": true,
-                "type": "boolean"
-              },
-              "type": {
-                "const": "rsvp",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "channel",
-              "contacts"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "items": {
-                "items": {
-                  "properties": {
-                    "time": {
-                      "maxLength": 10,
-                      "type": "string"
-                    },
-                    "what": {
-                      "maxLength": 200,
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "time",
-                    "what"
-                  ],
-                  "type": "object"
-                },
-                "maxItems": 20,
-                "type": "array"
-              },
-              "type": {
-                "const": "agenda",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "items"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "board": {
-                "default": [],
-                "items": {
-                  "oneOf": [
-                    {
-                      "properties": {
-                        "kind": {
-                          "const": "color",
-                          "type": "string"
-                        },
-                        "value": {
-                          "pattern": "^#[0-9a-f]{6}$",
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "kind",
-                        "value"
-                      ],
-                      "type": "object"
-                    },
-                    {
-                      "properties": {
-                        "kind": {
-                          "const": "emoji",
-                          "type": "string"
-                        },
-                        "value": {
-                          "maxLength": 16,
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "kind",
-                        "value"
-                      ],
-                      "type": "object"
-                    },
-                    {
-                      "properties": {
-                        "kind": {
-                          "const": "text",
-                          "type": "string"
-                        },
-                        "value": {
-                          "maxLength": 60,
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "kind",
-                        "value"
-                      ],
-                      "type": "object"
-                    },
-                    {
-                      "properties": {
-                        "kind": {
-                          "const": "image",
-                          "type": "string"
-                        },
-                        "value": {
-                          "maxLength": 2048,
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "kind",
-                        "value"
-                      ],
-                      "type": "object"
-                    }
-                  ]
-                },
-                "maxItems": 12,
-                "type": "array"
-              },
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "text": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "type": {
-                "const": "dress",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "text"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "href": {
-                "maxLength": 2048,
-                "type": "string"
-              },
-              "iban": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "interactive": {
-                "default": true,
-                "type": "boolean"
-              },
-              "text": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "type": {
-                "const": "gift",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "text"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "text": {
-                "maxLength": 200,
-                "type": "string"
-              },
-              "type": {
-                "const": "signature",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "text"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "style": {
-                "default": "flourish",
-                "enum": [
-                  "flourish",
-                  "stars",
-                  "line"
-                ],
-                "type": "string"
-              },
-              "type": {
-                "const": "divider",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "href": {
-                "maxLength": 2048,
-                "type": "string"
-              },
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "type": {
-                "const": "music",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "href"
-            ],
-            "type": "object"
-          },
-          {
-            "properties": {
-              "id": {
-                "maxLength": 32,
-                "minLength": 1,
-                "type": "string"
-              },
-              "stamp": {
-                "anyOf": [
-                  {
-                    "enum": [
-                      "love",
-                      "rose",
-                      "dove",
-                      "castle",
-                      "moon",
-                      "cake",
-                      "sunflower",
-                      "shell",
-                      "butterfly",
-                      "star",
-                      "key",
-                      "rocket",
-                      "disco",
-                      "invader"
-                    ],
-                    "type": "string"
-                  },
-                  {
-                    "const": "",
-                    "type": "string"
-                  }
-                ]
-              },
-              "type": {
-                "const": "stamp",
-                "type": "string"
-              }
-            },
-            "required": [
-              "id",
-              "type",
-              "stamp"
-            ],
-            "type": "object"
-          }
-        ]
-      },
-      "propertyNames": {
-        "enum": [
-          "front-center",
-          "front-tl",
-          "front-tr",
-          "front-bl",
-          "back-center"
-        ],
-        "type": "string"
-      },
-      "type": "object"
-    }
-  },
-  "required": [
-    "blocks"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / guests
      Removed value: -{
-  "description": "The full guest list. Guests keep their id and link when matched by id or, failing that, by name.",
-  "items": {
-    "properties": {
-      "id": {
-        "type": "string"
-      },
-      "name": {
-        "maxLength": 80,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "name"
-    ],
-    "type": "object"
-  },
-  "maxItems": 1000,
-  "type": "array"
-}
    • removedInput schema / properties / lang
      Removed value: -{
-  "description": "Language guests read the letter in",
-  "enum": [
-    "es",
-    "en",
-    "fr",
-    "pt",
-    "it",
-    "de"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / nameFallback
      Removed value: -{
-  "description": "What {name} reads as without a guest (default: \"Dear Guest\" in the letter language)",
-  "maxLength": 60,
-  "type": "string"
-}
    • removedInput schema / properties / preset
      Removed value: -{
-  "description": "Start from an occasion preset (pre-filled blocks). On update it only changes the occasion.",
-  "enum": [
-    "birthday",
-    "wedding",
-    "party",
-    "baby",
-    "dinner",
-    "graduation",
-    "event",
-    "letter"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / seal
      Removed value: -{
-  "description": "Wax seal mark: \"\" none, \"_\" plain, \"icon:<id>\", \"ini:ABC\", \"duo:A|J\"",
-  "maxLength": 16,
-  "type": "string"
-}
    • removedInput schema / properties / sealShape
      Removed value: -{
-  "enum": [
-    "scallop",
-    "round",
-    "flower",
-    "octagon"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / style
      Removed value: -{
-  "description": "Look of the letter and envelope (see catalog.styles)",
-  "enum": [
-    "parchment",
-    "midnight",
-    "romance",
-    "botanical",
-    "notebook",
-    "minimal",
-    "launch",
-    "groovy",
-    "deco",
-    "ivory",
-    "brutal",
-    "bubblegum",
-    "confetti",
-    "typewriter",
-    "pocket"
-  ],
-  "type": "string"
-}
  2. First observed

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses partial-update merge semantics (lang, style kept), link stability, that guests replaces while preserving ids/links and addGuests appends, image copying at full size, and the empty-body error. It omits auth/rate-limit context and reversibility, so not a 5.

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?

Front-loaded with the core action and merge semantics, then layered detail on body fields. Every sentence carries information, though the final sentence packs several unrelated field notes into one dense block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers merge behavior, error handling, and body-field semantics well. The gap is the required id/editKey parameters, which an agent must infer from name alone.

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 0% and the two required params (id, editKey) are undocumented, so the description must compensate. It does for the free-form body: field-level semantics for guests, addGuests, italic/fontStyle, and custom.frame enum values. The required id/editKey params remain unexplained, keeping it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Change a letter") that cleanly separates it from create_letter, delete_letter, and get_letter. It also clarifies the scope is partial: only fields sent are changed. It doesn't explicitly name sibling alternatives, but the verb alone disambiguates.

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?

Gives concrete usage context: you may send the same object get_letter returned, including its card wrapper, and warns that a body with no letter fields is an error rather than a silent success. This tells the agent both a valid calling pattern and a misuse case. No explicit when-not or named alternatives beyond get_letter's return shape.

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

All Magic Envelope toolsInspect
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