Formify — AI Assisted E-Signing

Update Draft

update_draft

DestructiveIdempotent

Update an existing draft. The draft must still have status draft. This is a full draft configuration update: include the complete signeeDetails list you want to keep, because signees not included may be removed. fileId is optional; if omitted, the draft keeps its current file.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	Updated 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	Complete desired pre-filled form field values for the draft. Use exact field names from get_file_fields.
`fileId`	No	Optional replacement file ID from upload_file. If omitted, the draft keeps its current file.
`userId`	No	User ID to assign as draft owner
`draftId`	Yes	Unique identifier of the draft to update
`language`	No	Language for the eventual signing invitation
`aiAssistant`	No	Optional AI assistant that helps signees while reviewing the document. Requires the aiAssistant capability.
`signeeDetails`	No	Complete desired signee list for the draft. Pass [] to remove all signees. Any existing signees not included may be removed.
`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
`fieldsReadonlyMode`	No	Form field read-only mode. Set to 'filled' when pre-filled fields 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."

First observedSep 10, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description goes beyond them by spelling out the replace semantics ('signees not included may be removed') and that it is a whole-configuration overwrite. It omits auth/permission requirements and error behavior, which are the remaining behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with the operation and its precondition, then the destructive signeeDetails rule, then the fileId fallback. No sentence is redundant against the schema or annotations.

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 mutation tool with no output schema, the description supplies the crucial replace-vs-merge semantics and the status precondition while the very detailed input schema handles per-field detail. Remaining gaps (permissions, side effects on non-included fields beyond signees) are minor but real.

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 100%, so the baseline is 3, and the description genuinely adds meaning: it clarifies that fileId is optional with a defined fallback and that signeeDetails is a full replacement list where omission means removal. It does not add anything for the many other parameters, which the schema already documents richly.

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?

States a specific verb and resource ('Update an existing draft') and immediately scopes the operation as a 'full draft configuration update' with a status precondition. It does not, however, name or contrast with adjacent siblings such as update_signee or update_template, so an agent still has to infer boundaries from the resource name alone.

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 a real precondition ('The draft must still have status draft') and a clear operating instruction for the signeeDetails list plus the optional fileId fallback. It stops short of explicit when-not or alternative-tool routing, but the usage context is concrete rather than implied.

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?