Why create and send are two different calls
The most consequential decision in the Usign API is a thing it refuses to do: there is no argument that creates a contract and dispatches it in the same breath.
Most e-signature APIs let you create and send a document in one request. It is the obvious design. It is also the reason integrating one with an autonomous agent is nerve-racking: a single malformed call, one hallucinated email address, and a legal agreement is in a stranger's inbox with your company's name on it.
Usign splits that into two calls, and no combination of parameters puts them back together.
The failure mode being designed against
Picture an agent handed a paragraph of messy text: “contract Maya, Devon and the person who replied on Thursday, usual rate.” A good model does well here most of the time. The interesting question is what happens the rest of the time.
With a combined create-and-send endpoint, a misparse is delivered. Emails are out. Signing links are live. Someone may already have signed a contract with the wrong fee in it. Your recovery options are a void, an apology, and a conversation with legal.
With a split, the same misparse produces drafts: rows in a database that nobody has seen, that cost nothing, and that a human deletes in ten seconds.
What the API actually does
POST /v1/contracts creates a contract in draft. Over MCP, usign_create_contract and usign_create_contracts_bulk pin dispatch to false — the parameter is not exposed, so there is nothing for an agent to set.
POST /v1/contracts/:id/send is the second call. It flips the status to sent, mints per-signer signing tokens, and dispatches the please-sign emails. Over MCP that is usign_send_contract, one contract at a time.
Everything expensive is in the second call. Everything an agent is likely to get wrong is visible after the first.
The annotations do real work
MCP lets a server label what a tool does. Usign's labels are load-bearing rather than decorative:
| Tool | Annotation | Effect on a well-behaved client |
|---|---|---|
usign_preview_contract | readOnlyHint | Runs freely — writes nothing |
usign_create_contract | destructiveHint: false | Runs without a confirmation prompt |
usign_create_contracts_bulk | destructiveHint: false | Same — drafts are cheap |
usign_send_contract | destructiveHint: true | Client raises its own confirmation gate |
usign_void_contract | destructiveHint: true | Same, and a reason is required |
A client that honours annotations gives you a confirmation step for free. A client that ignores them still cannot send by accident, because sending is a separate call it has to decide to make. The protection does not depend on the client behaving.
Preview is the third piece
usign_preview_contract renders a contract against your merge-field values and returns a validation block — without writing anything at all. Missing required fields, unfilled signer roles, and malformed values surface as validation errors rather than as a create that fails halfway through a batch.
The full loop, then: read the template → preview → create drafts → confirm → send. Three cheap reversible steps before the one that is neither.
What the split costs you
One extra round trip per contract, and an agent that has to be told it will need to come back. That is the entire bill.
In exchange, the worst realistic outcome of an agent misunderstanding you drops from a signed agreement on wrong terms to a draft nobody read. That is not a close trade.
And when something does get out
usign_void_contract cancels with a required reason and emails a withdrawal to anyone who has not signed. There is no delete, over MCP or anywhere else. A contract that existed continues to have existed, and the audit log says so — which is the property that makes the whole system worth trusting in the first place.
See the tools
Eleven tools, annotated so your client knows what needs a human.