Tool reference
A connected assistant calls these tools. Each call goes through Korala’s public HTTP API, so quota, billing, validation and the audit trail apply as they do for any integration.
The Permission column names the choice on the consent page. View stands for “View documents and templates”.
A permission covers more than the tools listed under it. The connection’s token works against the REST API directly. Create and edit templates also allows deleting, duplicating and replacing the file of any template in your organization. Prepare documents also allows renaming a draft and removing its recipients and fields.
Drafts
| Tool | What it does | Inputs | Permission |
|---|---|---|---|
create_draft_link | Turns a Markdown agreement into an “Open in Korala” link. You open the link, review the rendered draft and choose Save in Korala. The tool saves and sends nothing. Anyone with the link can read the draft, so use example data. | name, source, sampleData?, pageSize? (A4 or Letter) | None. Works with no account through the local @korala/mcp package. |
The draft travels in the URL fragment, which your browser does not send to a server. The encoded draft can hold up to 65,536 characters.
Templates
| Tool | What it does | Inputs | Permission |
|---|---|---|---|
list_templates | Lists the reusable templates in your organization. | search?, page?, limit? (1 to 100) | View |
get_template | Returns one template with its signer roles and fields. Markdown templates include source and revision. | templateId | View |
preview_markdown_template | Renders a Markdown agreement without saving it. Returns the page count, the variables it expects and the signature roles it declares. | source, sampleData?, pageSize? | View |
create_markdown_template | Saves a Markdown agreement as a reusable template. Each ::signature role becomes a signer role. Saving sends nothing. | name, description?, source, sampleData?, pageSize? | Create and edit templates |
create_document_from_template | Creates a draft document from a template. You assign one person to each signer role and supply the data that fills the template. Nothing goes out until send_document. This counts against your plan on plans that charge per document created from a template. | templateId, name, signers (role, name, email each), templateData? for Markdown templates, variables? for PDF and DOCX templates | Prepare documents |
source accepts up to 131,072 bytes, so text with non-ASCII characters reaches the limit sooner. See Markdown templates for the syntax. create_document_from_template matches roles by name, ignores case, and fails when a role has no person or two people.
Documents
| Tool | What it does | Inputs | Permission |
|---|---|---|---|
list_documents | Lists documents, newest first. Filters by status or a name search. | status? (draft, pending, completing, completed, failed, voided, expired), search?, page?, limit? (1 to 100) | View |
get_document | Returns one document with its status, its signers and who has signed, and its fields. A completed document includes a time-limited download URL for the signed PDF. | documentId | View |
get_audit_trail | Returns the audit trail: created, sent, viewed, signed, declined and completed events with timestamps. | documentId | View |
create_upload_url | Step 1 of a PDF upload. Returns a documentId and a presigned uploadUrl. The agent sends the file bytes to uploadUrl with PUT, then calls confirm_upload. | filename, contentType (application/pdf) | Prepare documents |
confirm_upload | Step 2 of a PDF upload. Creates the draft document. | documentId, name? | Prepare documents |
get_form_fields | Lists the fillable form fields inside an uploaded PDF, with page, position and size. An assistant cannot see the PDF, so it uses this to put a signature on the form’s own signature line. Returns an empty list for a flat PDF. | documentId | View documents and templates |
add_signer | Adds a recipient to a draft. Sends nothing. | documentId, name, email, signingOrder? | Prepare documents |
add_field | Places a signature, initials, date, text or checkbox field for one signer. Positions and sizes use PDF points from the top-left of the page. Documents from a template carry their fields already, so this tool serves uploaded PDFs. | documentId, signerId, fieldType, pageNumber, xPosition, yPosition, width, height, label?, required? | Prepare documents |
send_document | Sends a draft to its signers. This emails real people and counts against your plan. The one exception is a document made with a test-mode API key. Without the permission, the tool returns a reviewUrl where you review and send the document yourself. | documentId | Send and void documents |
void_document | Cancels a document so that nobody can sign it. You cannot undo a void. Without the permission, the tool returns a reviewUrl. | documentId | Send and void documents |
A trailing ? marks an optional input.
Chat assistants cannot upload local files, so create_upload_url and confirm_upload serve coding agents that can make HTTP requests. In a chat, create the document from a Markdown template.
Korala marks send_document and void_document as destructive. Assistants that honor the mark, such as ChatGPT, ask you to confirm before they call either tool.
Worked example
You are connected with Send and void documents off.
You: I need an NDA for Anna Novak, [email protected]. My company is Acme s.r.o.
The assistant calls list_templates with search: "NDA" and finds nothing. It writes a one-page mutual NDA in Markdown with two signature roles, company and recipient, and calls preview_markdown_template.
Assistant: The draft is one page. It expects
company.name,recipient.nameandeffective_date, and it has two signature roles: company and recipient. Who signs for Acme, and what is the effective date?
You: I sign, [email protected], Jan Dvorak. Effective today.
The assistant calls create_markdown_template, then create_document_from_template with both signers and the data.
Assistant: I saved the template “Mutual NDA” and created the document “NDA - Anna Novak”. Its ID is
7d0c1f5e-2a4b-4c8d-9e1f-3b6a5c7d8e9fand its status is draft. I have sent nothing.
You: Send it.
The assistant calls send_document. The connection lacks the permission, so the tool returns a review link.
Assistant: This connection cannot send. Review and send the document here:
https://korala.ai/documents/7d0c1f5e-2a4b-4c8d-9e1f-3b6a5c7d8e9f
With Send and void documents on, the same call sends the document, and the assistant reports the status pending. Ask “Has Anna signed?” later, and the assistant answers from get_document.