Skip to main content
Glama

postedly_upload_document

Stores one recipient-facing PDF from its exact bytes, supplied as canonical base64, without a browser. Accepts a valid, unencrypted PDF up to 10 MiB decoded; for postcard, a JPEG or PNG photo or front image for composing a postcard is also accepted (PNG at most 4 megapixels; use a JPEG for larger pictures). When expectedSha256 is supplied, a mismatch rejects the upload; a matching hash confirms byte integrity, not content correctness. Returns a private document ID, page count, byte count, SHA-256 and an authenticated preview URL. Service-specific layout checks run at quote time. Authenticated multipart POST /api/documents on the same OAuth connection is the equivalent HTTP upload. Does not create a quote, take payment or send anything.

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": {
      "service": "<service>",
      "filename": "<filename>",
      "contentBase64": "<contentBase64>"
    },
    "name": "postedly_upload_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
serviceYes
filenameYesFilename only, without a local path.
contentBase64YesStandard padded base64 of the exact file bytes. No data URL prefix or whitespace.
expectedSha256NoOptional SHA-256 computed from the original file bytes; a mismatch rejects the upload.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • removedInput schema / oneOf
      Removed value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "contentBase64"
      -      ]
      -    },
      -    "required": [
      -      "file"
      -    ]
      -  },
      -  {
      -    "not": {
      -      "required": [
      -        "file"
      -      ]
      -    },
      -    "required": [
      -      "filename",
      -      "contentBase64"
      -    ]
      -  }
      -]
    • changedInput schema / properties / contentBase64 / description
      Previous value: -"Standard padded base64 of actual file bytes, for clients that can read the exact bytes. No data URL prefix or whitespace; never invent base64."New value: +"Standard padded base64 of the exact file bytes. No data URL prefix or whitespace."
    • removedInput schema / properties / file
      Removed value: -{
      -  "additionalProperties": false,
      -  "properties": {
      -    "download_url": {
      -      "description": "Actual temporary HTTPS download URL supplied by ChatGPT; never invent a URL.",
      -      "maxLength": 8192,
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "file_id": {
      -      "maxLength": 256,
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "file_name": {
      -      "maxLength": 180,
      -      "minLength": 1,
      -      "type": "string"
      -    },
      -    "mime_type": {
      -      "enum": [
      -        "application/pdf",
      -        "application/octet-stream"
      -      ],
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "download_url",
      -    "file_id"
      -  ],
      -  "type": "object"
      -}
    • changedInput schema / properties / filename / description
      Previous value: -"Filename only, without a local path. Optional for native attachments; defaults to their file_name or Attachment.pdf."New value: +"Filename only, without a local path."
    • changedInput schema / required
      Previous value: -[
      -  "service"
      -]New value: +[
      +  "service",
      +  "filename",
      +  "contentBase64"
      +]
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "https://json-schema.org/draft/2020-12/schema",
      -  "anyOf": [
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "document": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "bytes": {
      -              "maximum": 10485760,
      -              "minimum": 1,
      -              "type": "integer"
      -            },
      -            "contentType": {
      -              "const": "application/pdf"
      -            },
      -            "id": {
      -              "minLength": 1,
      -              "type": "string"
      -            },
      -            "name": {
      -              "type": "string"
      -            },
      -            "pages": {
      -              "maximum": 50,
      -              "minimum": 1,
      -              "type": "integer"
      -            },
      -            "previewUrl": {
      -              "format": "uri-reference",
      -              "type": "string"
      -            },
      -            "sha256": {
      -              "pattern": "^[a-f0-9]{64}$",
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "id",
      -            "name",
      -            "pages",
      -            "bytes",
      -            "sha256",
      -            "previewUrl",
      -            "contentType"
      -          ],
      -          "type": "object"
      -        },
      -        "documentId": {
      -          "minLength": 1,
      -          "type": "string"
      -        },
      -        "message": {
      -          "type": "string"
      -        },
      -        "previewRequiresAuthentication": {
      -          "const": true
      -        }
      -      },
      -      "required": [
      -        "documentId",
      -        "document",
      -        "previewRequiresAuthentication",
      -        "message"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "error": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "code": {
      -              "minLength": 1,
      -              "type": "string"
      -            },
      -            "details": {
      -              "additionalProperties": false,
      -              "properties": {
      -                "addressRole": {
      -                  "enum": [
      -                    "recipient",
      -                    "sender"
      -                  ]
      -                },
      -                "canSendAsEntered": {
      -                  "type": "boolean"
      -                }
      -              },
      -              "required": [
      -                "addressRole",
      -                "canSendAsEntered"
      -              ],
      -              "type": "object"
      -            },
      -            "message": {
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "code",
      -            "message"
      -          ],
      -          "type": "object"
      -        }
      -      },
      -      "required": [
      -        "error"
      -      ],
      -      "type": "object"
      -    }
      -  ],
      -  "type": "object"
      -}New value: +null
  2. Changed6 schema fields changed
    • addedInput schema / oneOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "contentBase64"
      +      ]
      +    },
      +    "required": [
      +      "file"
      +    ]
      +  },
      +  {
      +    "not": {
      +      "required": [
      +        "file"
      +      ]
      +    },
      +    "required": [
      +      "filename",
      +      "contentBase64"
      +    ]
      +  }
      +]
    • changedInput schema / properties / contentBase64 / description
      Previous value: -"Standard padded base64 of the exact file bytes. No data URL prefix or whitespace."New value: +"Standard padded base64 of actual file bytes, for clients that can read the exact bytes. No data URL prefix or whitespace; never invent base64."
    • addedInput schema / properties / file
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "download_url": {
      +      "description": "Actual temporary HTTPS download URL supplied by ChatGPT; never invent a URL.",
      +      "maxLength": 8192,
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "file_id": {
      +      "maxLength": 256,
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "file_name": {
      +      "maxLength": 180,
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "mime_type": {
      +      "enum": [
      +        "application/pdf",
      +        "application/octet-stream"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "download_url",
      +    "file_id"
      +  ],
      +  "type": "object"
      +}
    • changedInput schema / properties / filename / description
      Previous value: -"Filename only, without a local path."New value: +"Filename only, without a local path. Optional for native attachments; defaults to their file_name or Attachment.pdf."
    • changedInput schema / required
      Previous value: -[
      -  "service",
      -  "filename",
      -  "contentBase64"
      -]New value: +[
      +  "service"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "anyOf": [
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "document": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "bytes": {
      +              "maximum": 10485760,
      +              "minimum": 1,
      +              "type": "integer"
      +            },
      +            "contentType": {
      +              "const": "application/pdf"
      +            },
      +            "id": {
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "name": {
      +              "type": "string"
      +            },
      +            "pages": {
      +              "maximum": 50,
      +              "minimum": 1,
      +              "type": "integer"
      +            },
      +            "previewUrl": {
      +              "format": "uri-reference",
      +              "type": "string"
      +            },
      +            "sha256": {
      +              "pattern": "^[a-f0-9]{64}$",
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "id",
      +            "name",
      +            "pages",
      +            "bytes",
      +            "sha256",
      +            "previewUrl",
      +            "contentType"
      +          ],
      +          "type": "object"
      +        },
      +        "documentId": {
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "message": {
      +          "type": "string"
      +        },
      +        "previewRequiresAuthentication": {
      +          "const": true
      +        }
      +      },
      +      "required": [
      +        "documentId",
      +        "document",
      +        "previewRequiresAuthentication",
      +        "message"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "error": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "code": {
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "details": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "addressRole": {
      +                  "enum": [
      +                    "recipient",
      +                    "sender"
      +                  ]
      +                },
      +                "canSendAsEntered": {
      +                  "type": "boolean"
      +                }
      +              },
      +              "required": [
      +                "addressRole",
      +                "canSendAsEntered"
      +              ],
      +              "type": "object"
      +            },
      +            "message": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "code",
      +            "message"
      +          ],
      +          "type": "object"
      +        }
      +      },
      +      "required": [
      +        "error"
      +      ],
      +      "type": "object"
      +    }
      +  ],
      +  "type": "object"
      +}
  3. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing the 10 MiB decoded cap, unencrypted-PDF restriction, postcard image allowances with a PNG megapixel limit, and hash-mismatch rejection behavior. It also clarifies that a matching hash proves byte integrity but not content correctness, and describes exactly what is returned (document ID, page count, bytes, SHA-256, authenticated preview URL).

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 what it does and what it accepts, then constraints, then return values, then boundaries — no filler sentences. The trade-off is density: several long multi-clause sentences make it more of a paragraph block than a scannable structure, though each clause carries information.

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?

No output schema exists, and the description compensates by enumerating the returned fields and the preview URL. For a 4-parameter mutation tool, all the decision-relevant facts — format limits, hash behavior, postcard exception, and scope exclusions — are present.

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

Parameters5/5

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

With schema coverage at 75%, the description adds real meaning: it explains the decoded-size constraint that explains contentBase64's maxLength, the service-specific exception for postcard image uploads, and the precise semantics of expectedSha256 (mismatch rejects; match proves integrity, not correctness). These are interpretive details the schema's pattern and length constraints cannot convey.

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 concrete verb and resource ('Stores one recipient-facing PDF from its exact bytes') plus the mechanism ('without a browser'). It also explicitly disclaims adjacent capabilities ('Does not create a quote, take payment or send anything'), which separates it from siblings like quote, checkout, and delivery actions.

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 clear usage context: raw bytes vs. a browser upload, size/format preconditions, and the note that layout checks happen at quote time, implying the quote step follows this. It does not explicitly name the alternative tool to call afterwards (e.g., prepare/quote), so the routing is implied rather than spelled out.

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.

Resources