Formify — AI Assisted E-Signing

Create Draft

create_draft

Create a draft document without sending invitations. Provide EXACTLY ONE source: fileId (from upload_file) or templateId (from list_templates). Sending both, or neither, is an error. Using templateId is how you preview a template before sending it: the template's document and signature fields are copied into the draft, you review or adjust them, then send_draft. The template itself is never affected. Signee details, contact methods, signature type, and signature coordinates are optional while drafting. Full validation occurs only when send_draft is called. Call get_file_fields after upload_file if the PDF has form fields that should be pre-filled and saved in the draft. The draft name will become visible to signees when the draft is sent, so it should be a clear, human-readable title, not the uploaded filename. If deriving it from a PDF filename, strip the file extension unless the user explicitly wants to keep it. PREVIEW USE CASE: drafts are the recommended way to preview an uploaded document before sending. When the user wants to verify that signature fields, ID scan placeholders, or pre-filled values look correct, build the full configuration here, call get_draft_file_url to retrieve a one-time PDF preview, let the user verify (and adjust via update_draft if needed), then call send_draft to send.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	Yes	Human-readable draft title that will be visible to signees when sent. If deriving from an uploaded PDF filename, strip the file extension (e.g. 'contract.pdf' → 'contract') unless the user explicitly wants the extension.
`fields`	No	Optional form fields to pre-fill and save in the draft. Use exact field names from get_file_fields.
`fileId`	No	File ID from upload_file. Mutually exclusive with templateId; exactly one of the two is required.
`userId`	No	User ID to assign as draft owner. Defaults to the authenticated user.
`language`	No	Language for the eventual signing invitation
`templateId`	No	Template ID from list_templates. Mutually exclusive with fileId; exactly one of the two is required. Copies the template's document and signature fields into the draft, including any contact details it stores. Requires the templates capability.
`aiAssistant`	No	Optional AI assistant that helps signees while reviewing the document. Requires the aiAssistant capability.
`signeeDetails`	No	Optional list of signees to save in the draft. Entries may be incomplete during the draft phase; fullName and a contact method are required before sending.
`sharingSetting`	No	Whether the draft is private or shared with other users on the account
`personalMessage`	No	Optional personal message for the eventual signing invitation. Maximum 500 characters.
`enableSigningOrder`	No	Enable sequential signing order when the draft is sent (requires signingOrder capability)
`fieldsReadonlyMode`	No	Form field read-only mode. Set to 'filled' when providing pre-filled values that should be locked for signers.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 8, 2026

changedInput schema / properties / signeeDetails / items / properties / idScanBox / description

Previous value: -"ID scan placeholder coordinates. Required when a live document is sent with signatureType: 'digital_ink_id_scan'. Optional while saving a draft; full validation happens only when the draft is sent. The ID document itself is captured and read on Formify's signing page; only the placeholder's position is configured here, and no image or document data passes through this API.\n\nCoordinate system: origin is at the top-left; x increases to the right and y increases downward. All coordinates and field sizes are specified in points (pt). The position (x, y) always refers to the top-left corner of the field.\n\nStandard ID scan field size at scale = 1.0 is 218 × 138 pt.\n\nIMPORTANT: Always check the actual page size of the PDF before calculating coordinates — do not assume A4. Common page sizes:\n- A4: 210 × 297 mm → 595 × 842 pt at 72 pt/in (pt = mm × 72 / 25.4). Example bottom-right: x = 595 - 218 = 377, y = 842 - 138 = 704, page = 0.\n- US Letter: 8.5 × 11 in → 612 × 792 pt at 72 pt/in. Example bottom-right: x = 612 - 218 = 394, y = 792 - 138 = 654, page = 0.\n\nCollision: Formify does not detect overlapping fields. You must ensure that no two fields share the same page and position, or overlap. Fields are fully opaque — placing a field on top of existing document content will hide it. Use scale to shrink a field when space is limited. Overlapping fields or fields placed over content result in a poor signing experience."New value: +"ID scan placeholder coordinates. Required when a live document is sent with signatureType: 'digital_ink_id_scan'. Optional while saving a draft; full validation happens only when the draft is sent. The ID document itself is captured and read on Formify's signing page; only the placeholder's position is configured here, and no image or document data passes through this API. The scanned front side is then placed in the signed document at this position, so the sender needs a legal basis for keeping a copy of the identity document there (see signatureType).\n\nCoordinate system: origin is at the top-left; x increases to the right and y increases downward. All coordinates and field sizes are specified in points (pt). The position (x, y) always refers to the top-left corner of the field.\n\nStandard ID scan field size at scale = 1.0 is 218 × 138 pt.\n\nIMPORTANT: Always check the actual page size of the PDF before calculating coordinates — do not assume A4. Common page sizes:\n- A4: 210 × 297 mm → 595 × 842 pt at 72 pt/in (pt = mm × 72 / 25.4). Example bottom-right: x = 595 - 218 = 377, y = 842 - 138 = 704, page = 0.\n- US Letter: 8.5 × 11 in → 612 × 792 pt at 72 pt/in. Example bottom-right: x = 612 - 218 = 394, y = 792 - 138 = 654, page = 0.\n\nCollision: Formify does not detect overlapping fields. You must ensure that no two fields share the same page and position, or overlap. Fields are fully opaque — placing a field on top of existing document content will hide it. Use scale to shrink a field when space is limited. Overlapping fields or fields placed over content result in a poor signing experience."

changedInput schema / properties / signeeDetails / items / properties / signatureType / description

Previous value: -"Signature method. Optional while drafting. Non-default methods require account capabilities. Identity verification for bankid_identification, digital_ink_id_scan and face_liveness is performed by Formify's signing page in the signer's browser, after the invitation is sent. This parameter only selects the method: no identity document, biometric data or national identity number is sent to, returned by or stored through this API."New value: +"Signature method. Optional while drafting. Non-default methods require account capabilities. Identity verification for bankid_identification, digital_ink_id_scan and face_liveness is performed by Formify's signing page in the signer's browser, after the invitation is sent. This parameter only selects the method: no identity document, biometric data or national identity number is sent to, returned by or stored through this API. digital_ink_id_scan additionally places an image of the signer's identity document (front side) in the signed document, at the idScanBox position. Reproducing a copy of an identity document requires the sender's own legal basis: before selecting this method, tell the user that a copy of the ID document will be embedded in the signed document and get an explicit yes. Suggest another signing method if they do not need a copy of the identity document in the document."

Changed2 schema fields changedSep 22, 2026

changedInput schema / properties / signeeDetails / items / properties / idScanBox / description

Previous value: -"ID scan placeholder coordinates. Required when a live document is sent with signatureType: 'digital_ink_id_scan'. Optional while saving a draft; full validation happens only when the draft is sent.\n\nCoordinate system: origin is at the top-left; x increases to the right and y increases downward. All coordinates and field sizes are specified in points (pt). The position (x, y) always refers to the top-left corner of the field.\n\nStandard ID scan field size at scale = 1.0 is 218 × 138 pt.\n\nIMPORTANT: Always check the actual page size of the PDF before calculating coordinates — do not assume A4. Common page sizes:\n- A4: 210 × 297 mm → 595 × 842 pt at 72 pt/in (pt = mm × 72 / 25.4). Example bottom-right: x = 595 - 218 = 377, y = 842 - 138 = 704, page = 0.\n- US Letter: 8.5 × 11 in → 612 × 792 pt at 72 pt/in. Example bottom-right: x = 612 - 218 = 394, y = 792 - 138 = 654, page = 0.\n\nCollision: Formify does not detect overlapping fields. You must ensure that no two fields share the same page and position, or overlap. Fields are fully opaque — placing a field on top of existing document content will hide it. Use scale to shrink a field when space is limited. Overlapping fields or fields placed over content result in a poor signing experience."New value: +"ID scan placeholder coordinates. Required when a live document is sent with signatureType: 'digital_ink_id_scan'. Optional while saving a draft; full validation happens only when the draft is sent. The ID document itself is captured and read on Formify's signing page; only the placeholder's position is configured here, and no image or document data passes through this API.\n\nCoordinate system: origin is at the top-left; x increases to the right and y increases downward. All coordinates and field sizes are specified in points (pt). The position (x, y) always refers to the top-left corner of the field.\n\nStandard ID scan field size at scale = 1.0 is 218 × 138 pt.\n\nIMPORTANT: Always check the actual page size of the PDF before calculating coordinates — do not assume A4. Common page sizes:\n- A4: 210 × 297 mm → 595 × 842 pt at 72 pt/in (pt = mm × 72 / 25.4). Example bottom-right: x = 595 - 218 = 377, y = 842 - 138 = 704, page = 0.\n- US Letter: 8.5 × 11 in → 612 × 792 pt at 72 pt/in. Example bottom-right: x = 612 - 218 = 394, y = 792 - 138 = 654, page = 0.\n\nCollision: Formify does not detect overlapping fields. You must ensure that no two fields share the same page and position, or overlap. Fields are fully opaque — placing a field on top of existing document content will hide it. Use scale to shrink a field when space is limited. Overlapping fields or fields placed over content result in a poor signing experience."

changedInput schema / properties / signeeDetails / items / properties / signatureType / description

Previous value: -"Signature method. Optional while drafting. Non-default methods require account capabilities."New value: +"Signature method. Optional while drafting. Non-default methods require account capabilities. Identity verification for bankid_identification, digital_ink_id_scan and face_liveness is performed by Formify's signing page in the signer's browser, after the invitation is sent. This parameter only selects the method: no identity document, biometric data or national identity number is sent to, returned by or stored through this API."

Changed3 schema fields changedSep 16, 2026

changedInput schema / properties / fileId / description

Previous value: -"File ID from upload_file. Required for drafts; templateId is not supported."New value: +"File ID from upload_file. Mutually exclusive with templateId; exactly one of the two is required."

addedInput schema / properties / templateId

Added value: +{
+  "description": "Template ID from list_templates. Mutually exclusive with fileId; exactly one of the two is required. Copies the template's document and signature fields into the draft, including any contact details it stores. Requires the templates capability.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "fileId",
-  "name"
-]New value: +[
+  "name"
+]

First observedSep 10, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description discloses behavior well beyond the annotations: validation is deferred until send_draft, the source template is never affected, the draft name becomes visible to signees on send, and the preview flow yields a one-time PDF URL. These are non-obvious operational traits that the readOnlyHint/destructiveHint flags alone would not convey.

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?

The core rule is front-loaded in the first two sentences, which is good, but the description is long and duplicates schema content (the name-visibility and filename-extension guidance appears both here and in the name parameter) and revisits the preview idea in both the templateId paragraph and the final PREVIEW USE CASE block. Given 12 parameters and nested objects, most of the length is defensible.

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 12-parameter tool with nested objects and no output schema, the description is unusually complete on workflow, validation timing, and template semantics. The one gap is that it never states what create_draft returns (e.g., a draft ID) even though there is no output schema and later steps (send_draft, get_draft_file_url) clearly depend on that identifier.

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 description coverage is 100% and extremely detailed, so the baseline is 3. The description adds one genuinely cross-cutting semantic the schema does not state cleanly: signee details, contact methods, signature type, and coordinates are optional while drafting because full validation happens only at send time, which shapes how an agent should populate the parameters.

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?

The opening sentence gives a specific verb and resource ("Create a draft document") and immediately scopes it with "without sending invitations," which sharply distinguishes it from the closest sibling send_draft. The rest of the description reinforces the distinction by contrasting the draft phase with the send phase and positioning drafts as the preview mechanism.

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?

It states an explicit either/or rule ("Provide EXACTLY ONE source: fileId ... or templateId"), the failure condition ("Sending both, or neither, is an error"), and the step-by-step preview workflow naming the downstream tools (get_file_fields, get_draft_file_url, update_draft, send_draft). It also gives a dedicated "PREVIEW USE CASE" telling the agent exactly when this tool is the right choice.

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

All Formify — AI Assisted E-Signing 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?