zsign

Send Envelope for Signature

send_envelope

Send a PDF for legally binding signature, or leave it as a Draft for a human to approve. Immediate send costs 1 credit. Provide the PDF either as document_base64 OR as a public https document_url (max 10MB). recipients = [{"name": "...", "email": "...", "role": "signer"}]. Each recipient gets a signing email; poll get_envelope_status for progress. Requires Authorization: Bearer zs_....

auto_send defaults true (existing one-tool send). Set auto_send=false or draft=true to create a Draft: status Draft, no credit debit, no invite emails. draft=true always wins if both flags are set. Then a human Approves/Sends in the dashboard, or call send_draft.

Immediate send: the PDF is REJECTED unless it contains signing-field placeholder tags. Draft mode accepts an untagged PDF (human places fields) or optional fields. zSign field placeholder syntax:

Format: {type:party:name} -- add * after the type to mark the field required, e.g. {signature*:signer}
Types: signature, initials, text, date, radio
party must exactly match the recipient's "role" value passed when sending (MCP default role is "signer")
name is optional for signature/initials/date and REQUIRED for text fields; letters, digits, and underscores only
radio fields take FOUR parts: {radio:party:group:option}. Every tag sharing a party and group forms one exclusive set -- the signer picks exactly one, and the chosen option is the value reported back. Mark the set required with {radio*:...} on any of its tags. group is letters/digits/underscores; option may also contain spaces and hyphens
radio tags must be visible text in the PDF body -- they cannot be the name of a PDF form field
Keep each tag on a single line in a standard font -- a tag split across lines is not detected
The tag's position in the document becomes the field's position; the signed value is drawn over it, and the tag itself is deleted when you upload -- signers never see it, and it is not in the completed document
Tags can be visible text in the PDF body, or the name of a PDF form field / annotation (except radio, which must be visible text) Examples: {signature*:signer}, {initials:signer}, {text*:signer:full_name}, {date:signer:signed_on} Radio (visible text only): {radio*:signer:plan:Option 1}, {radio*:signer:plan:Option 2} Sample PDF: https://storage.googleapis.com/zsign-public/simple_contract_1.pdf Docs: https://zsign.io/docs/api

metadata is an optional flat object of string keys/values (max 50 keys) echoed back in every webhook for this envelope -- use it to carry your own record ids.

sequential (default true): recipients sign one at a time in list order. Set false so everyone can sign at once. Same flag as REST POST /api/v1/documents/send sequential.

documents: list of {filename, document_base64 | document_url, name?} to send several PDFs as ONE envelope (one credit, shared recipients, one signing link per signer; at most 10). Mutually exclusive with document_base64/document_url.

Input Schema

TableJSON Schema

Name	Required	Default
`name`	No
`draft`	No
`fields`	No
`filename`	No	document.pdf
`metadata`	No
`auto_send`	No
`documents`	No
`recipients`	No
`sequential`	No
`send_invite`	No
`document_url`	No
`document_base64`	No
`send_completion_email`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 12, 2026

addedInput schema / properties / documents

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Documents"
+}

Changed1 schema field changedSep 5, 2026

addedInput schema / properties / sequential

Added value: +{
+  "default": true,
+  "title": "Sequential",
+  "type": "boolean"
+}

Changed8 schema fields changedSep 5, 2026

addedInput schema / properties / auto_send

Added value: +{
+  "default": true,
+  "title": "Auto Send",
+  "type": "boolean"
+}

addedInput schema / properties / draft

Added value: +{
+  "default": false,
+  "title": "Draft",
+  "type": "boolean"
+}

addedInput schema / properties / fields

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Fields"
+}

addedInput schema / properties / recipients / anyOf

Added value: +[
+  {
+    "items": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / recipients / default
```
Added value: +null
```

removedInput schema / properties / recipients / items

Removed value: -{
-  "additionalProperties": true,
-  "type": "object"
-}

removedInput schema / properties / recipients / type
```
Removed value: -"array"
```
removedInput schema / required
```
Removed value: -[
-  "recipients"
-]
```

Changed3 schema fields changedSep 2, 2026

addedInput schema / properties / metadata

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Metadata"
+}

addedInput schema / properties / send_completion_email

Added value: +{
+  "default": true,
+  "title": "Send Completion Email",
+  "type": "boolean"
+}

addedInput schema / properties / send_invite

Added value: +{
+  "default": true,
+  "title": "Send Invite",
+  "type": "boolean"
+}

First observedJul 21, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes far beyond the annotations: discloses the 1-credit cost, that Draft mode has no credit debit or invite emails, that immediate send REJECTS untagged PDFs, the full field-tag syntax and its lifecycle (tags deleted on upload, never seen by signers), sequential signing default, and that metadata is echoed in every webhook. The non-idempotent, open-world, non-destructive profile is consistent with this text.

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?

Long, but front-loaded with the core decision (send vs draft) and organized into scannable mode/syntax sections. A few passages (the tag placement/visibility bullets) could be tightened, and the field-syntax block is heavy for a single paragraph, but nearly every line carries operational value.

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 13-parameter, zero-schema-coverage, non-idempotent mutation tool this is as complete as an agent needs: cost model, rejection preconditions, draft semantics, recipient/field syntax, portability flags (sequential, docs), and the status-polling follow-up. Return values are covered by the output schema, so omitting them is correct.

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?

With 0% schema coverage across 13 params, the description carries the burden and does so for document_base64/document_url (10MB limit), recipients structure/roles, auto_send, draft, metadata (max 50 keys, echo behavior), sequential, and documents (mutually exclusive, max 10). It leaves name, filename, send_invite, and send_completion_email undocumented, which is the only real gap.

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+resource ('Send a PDF for legally binding signature') and immediately distinguishes the two operating modes (immediate send vs Draft) that separate it from siblings like send_draft. An agent can tell exactly what this tool does 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes between modes: immediate send vs auto_send=false/draft=true, states draft=true wins on conflict, names the follow-up path (human dashboard approval or send_draft), and points to get_envelope_status for polling. Also names the alternative REST endpoint and mutual exclusivity with the documents list.

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

All zsign 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?