Skip to main content
Glama

postedly_prepare_document

Creates a private, single-use document-upload request with a 15-minute expiry and a 10 MiB file limit. Returns a request ID, a multipart upload endpoint for direct transfer of the file bytes, and a browser upload URL for a person who has the file when the agent cannot access it. For postcard, the upload may be the postcard PDF or a JPEG or PNG photo or front image, so a person can add a photo from a phone. Does not upload a document, create a quote or order, 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>"
    },
    "name": "postedly_prepare_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
serviceYes
filenameNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "https://json-schema.org/draft/2020-12/schema",
      -  "anyOf": [
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "documentRequestId": {
      -          "minLength": 1,
      -          "type": "string"
      -        },
      -        "expiresAt": {
      -          "type": "string"
      -        },
      -        "instructions": {
      -          "type": "string"
      -        },
      -        "maxFileBytes": {
      -          "const": 10485760
      -        },
      -        "uploadEncoding": {
      -          "const": "multipart/form-data"
      -        },
      -        "uploadEndpoint": {
      -          "format": "uri",
      -          "type": "string"
      -        },
      -        "uploadField": {
      -          "const": "file"
      -        },
      -        "uploadMethod": {
      -          "const": "POST"
      -        },
      -        "uploadUrl": {
      -          "format": "uri",
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "documentRequestId",
      -        "uploadUrl",
      -        "expiresAt",
      -        "uploadEndpoint",
      -        "uploadMethod",
      -        "uploadEncoding",
      -        "uploadField",
      -        "maxFileBytes",
      -        "instructions"
      -      ],
      -      "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. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "anyOf": [
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "documentRequestId": {
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "expiresAt": {
      +          "type": "string"
      +        },
      +        "instructions": {
      +          "type": "string"
      +        },
      +        "maxFileBytes": {
      +          "const": 10485760
      +        },
      +        "uploadEncoding": {
      +          "const": "multipart/form-data"
      +        },
      +        "uploadEndpoint": {
      +          "format": "uri",
      +          "type": "string"
      +        },
      +        "uploadField": {
      +          "const": "file"
      +        },
      +        "uploadMethod": {
      +          "const": "POST"
      +        },
      +        "uploadUrl": {
      +          "format": "uri",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "documentRequestId",
      +        "uploadUrl",
      +        "expiresAt",
      +        "uploadEndpoint",
      +        "uploadMethod",
      +        "uploadEncoding",
      +        "uploadField",
      +        "maxFileBytes",
      +        "instructions"
      +      ],
      +      "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.3/5.0
Behavior5/5

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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), it discloses the 15-minute expiry, 10 MiB cap, single-use privacy, and exactly what the call returns (request ID, multipart upload endpoint, browser upload URL). It also notes the postcard-specific accepted file types, which is behavior nothing in the structured fields carries.

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?

Four sentences, front-loaded with the core action and constraints, then returns, then the postcard nuance, then the negative scope. Dense but each sentence carries distinct information; slight redundancy between the 'single-use' framing and the closing negative list.

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?

With no output schema, the description usefully describes the return payload, which is the main gap it needed to fill. It is nearly complete for a 2-parameter tool, with 'filename' semantics and any failure/expiry behavior at the call site left unaddressed.

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 0%, so the description must carry parameter meaning. It explains the postcard case for 'service' (PDF, JPEG, or PNG photo or front image), but 'filename' is never mentioned, so half the parameters remain undocumented in both places.

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 precise verb and resource ('Creates a private, single-use document-upload request') plus its key constraints, then explicitly separates itself from siblings with 'Does not upload a document, create a quote or order, take payment or send anything.' An agent can distinguish it from postedly_upload_document and postedly_quote without opening any 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?

Gives clear conditions for use (a person has the file when the agent cannot access it) and clear exclusions (it does not itself upload, order, or pay). It stops short of naming a specific alternative sibling such as postedly_upload_document for the agent-side case, leaving that routing one inference away.

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