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_standard_forms | The government and agency forms Korala curates, each carrying the real form’s labels, validation and choose-one groups. Look here first when someone names a form. Says so when nothing matches, so you can offer to import their own PDF. | search | View |
describe_standard_form | A standard form’s signer roles and every field it asks for, without creating anything. Read it to gather the answers before adding the form. | publishedVersionId | View |
use_standard_form | Copy a standard form into the organization as a template, ready to make documents from. | publishedVersionId, name | Create and edit templates |
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. Fields come back summarized, 60 to a page, with fieldCount and nextFieldPage; fieldDetail: "full" returns every column a field carries, 20 to a page. | templateId, fieldPage, fieldDetail | 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, and each ::field a date, text, initials, checkbox, dropdown or radio for one of them. 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 |
add_template_field | Adds a field to a template, so every document made from it carries that field. Places it by coordinates, against text found in each generated document, or at a Word bookmark. A Markdown template keeps its signature fields in its source and refuses fields added from outside. | templateId, fieldType, width, height, signerRoleId?, placement?, pageNumber?, xPosition?, yPosition?, anchorText?, anchorPosition?, anchorOffsetX?, anchorOffsetY?, hideAnchor?, anchorMatchWholeWord?, bookmarkName?, mergeFieldName?, defaultValue?, and the field properties | Create and edit templates |
update_template_field | Changes a field on a template: moves it, resizes it, relabels it, reassigns it, or fixes a dropdown’s choices. Documents already created from the template keep the fields they were made with. | templateId, fieldId, and any input add_template_field takes except fieldType, with width and height optional here | Create and edit templates |
remove_template_field | Removes one field from a template. | templateId, fieldId | Create and edit templates |
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 search that matches the document name or a signer’s name or email. | 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. Fields come back summarized, 60 to a page, with fieldCount and nextFieldPage; fieldDetail: "full" returns every column a field carries, 20 to a page. | documentId, fieldPage, fieldDetail | View |
get_audit_trail | Returns the audit trail: created, sent, viewed, signed, declined and completed events with timestamps. | documentId | View |
request_pdf_upload | For an assistant that cannot send a file. Creates an empty draft and returns a Korala page where the user uploads the PDF, signed in as themselves. When the user says the file is there, the assistant calls confirm_upload, which fails until it is and then describes the PDF. Chat apps that support MCP Apps show the link as a card. | name? | Prepare documents |
upload_attached_pdf | Turns a PDF the user attached to the chat into a draft. ChatGPT passes an attachment to the tool as a temporary download link; Korala downloads it, refuses anything that is not a PDF or is over 25 MB, and never follows the link to a private address. Other assistants do not pass attachments to tools. | file, name? | Prepare documents, View documents |
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 and tells the assistant what Korala found in the file: page count, whether it is a fillable form and how many fields it declares, and whether it has a text layer. fieldOptions lists the ways to place fields on that file. With autoImportFormFields, Korala places a fillable form’s fields itself when the first signer is added. | documentId, name?, autoImportFormFields? | Prepare documents. The brief also needs View documents and templates |
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; the assistant then uses find_text. | documentId | View documents and templates |
add_signer | Adds a recipient to a draft. Sends nothing. The result says how many fields the signer already has, because a fillable PDF uploaded in the dashboard gets its form fields when the first signer is added. | documentId, name, email, signingOrder? | Prepare documents. The field count also needs View documents and templates |
import_form_fields | Places the fields a fillable PDF declares, for one signer, exactly where the form draws them; read-only boxes are left out. Repeating it skips what an earlier import placed. It does not know about fields the assistant placed by hand, so it goes first. A large file is imported in the background, and the result says so. Returns an error for a flat PDF. Korala does the same by itself for a PDF uploaded in the dashboard, when the first signer is added. | documentId, signerId, replaceExisting? | Prepare documents |
update_field | Moves, resizes, relabels or reassigns a field on a draft. For correcting a placement the assistant can see is wrong. Same coordinates as add_field. | documentId, fieldId, signerId?, xPosition?, yPosition?, width?, height?, and the field properties | Prepare documents |
remove_field | Removes one field from a draft: a duplicate, or one placed by mistake. | documentId, fieldId | Prepare documents |
remove_signer | Takes a signer off a draft, with every field they were given: one added by mistake, or left over from an earlier attempt. Only with the user’s agreement. | documentId, signerId | Prepare documents |
update_signer | Renames a signer on a draft or changes when they sign. Signers with the same order sign at the same time; a higher order waits for every lower one. The email address cannot change. | documentId, signerId, name?, signingOrder? | Prepare documents |
view_page | Shows one page of an uploaded PDF as an image. Rulers are drawn on it in the units add_field takes (points from the top-left corner), so the assistant reads positions off the page instead of converting pixels. Fields already placed are outlined and captioned with a number and their type, so it can check where its field landed. The result lists each numbered field with its signer’s name, as text, so a name in any script arrives intact. Refuses a rotated page. | documentId, pageNumber, showFields? | View documents and templates |
open_fields_panel | Opens the signing fields panel in a chat that shows apps (ChatGPT, Claude): a document’s pages with each field drawn in its signer’s colour, where the person drags a field into place, resizes it, nudges it with the arrow keys or removes it. Every change goes through update_field and remove_field over the same connection, and what the person changed reaches the assistant as context on its next turn. In ChatGPT the panel can also be opened from a conversation without asking the assistant; it then lists the 20 most recent drafts. In a client without apps nothing is drawn, and the result tells the assistant to give the fields editor link instead. | documentId? | View documents and templates |
fields_panel_page | One page as a clean image, without rulers or outlines, for the panel to draw fields on. Only the panel calls it; a client that keeps app-only tools from the model does not offer it. A rotated page is refused, as view_page refuses it. | documentId, pageNumber | View documents and templates |
read_text | Reads what an uploaded PDF says, a run of pages at a time, with columns kept side by side as printed. Only for an assistant that cannot read the file itself: one handed a document it has never seen (you uploaded it in Korala, or through the upload link) uses this to learn who the parties are and what the label beside each blank is called, in any language, before it searches for it. An assistant that has the file reads it there and does not call Korala. One answer holds about 20,000 characters and says which page to continue from, so the number of pages is no limit; the file may be up to 25 MB. Scanned pages have no text; the assistant looks at those with view_page. | documentId, fromPage?, toPage? | View documents and templates |
find_text | Finds a phrase in an uploaded PDF, or up to ten phrases in one call (texts), which costs Korala one read of the file instead of one per phrase. Each match comes with its page, its box and the whole line it sits on, so two “Signature” labels for different people can be told apart. Also returns page sizes and marks rotated pages. It reads files up to 25 MB and their first 150 pages. An assistant cannot see the PDF; this is how it finds the signature line on a flat one. | documentId, text?, texts? | View documents and templates |
add_field_at_text | Places a field against a phrase in the PDF: to the right of it, above it, below it, to the left, or over it. Korala works out the coordinates, and above or below a label makes the field no taller than the blank there. It refuses a place with no room, a rotated page, and a signer who is not on the document. When the phrase appears more than once the assistant has to say which. | documentId, signerId, fieldType, anchorText, occurrence?, position?, offsetX?, offsetY?, width?, height?, and the field properties | Prepare documents |
add_field | Places a field at exact coordinates, for a fillable PDF whose positions came from get_form_fields. The origin is the top-left corner of the page, x grows right and y grows down, as in an image; it is not the PDF-native bottom-left system. Units are PDF points (72 per inch), and xPosition/yPosition are the field’s own top-left corner. An agent working from a rendered page multiplies pixel values by page points ÷ image pixels; see Coordinates. Documents from a template carry their fields already, so this tool serves uploaded PDFs. Like add_field_at_text and update_field, it warns when the field lies on top of another field on the same page. | documentId, signerId, fieldType, pageNumber, xPosition, yPosition, width, height, and the field properties | Prepare documents |
find_blanks | Where an uploaded PDF looks like it is waiting to be filled in: every ruled line and labelled blank, with the words printed against it, the whole line it sits on, and a box a field would fit. It does not say what any blank is for; the assistant has the label and decides. A line drawn as a graphic is not text and is not found this way, so find_text still covers those. For a fillable PDF, import_form_fields is better. | documentId | View documents and templates |
add_fields | Places many fields in one call, each at coordinates or against text. Every entry is judged on its own: the answer says which were placed and why each of the others was not, so one bad entry does not cost the rest. The file is read once however many entries are anchored. | documentId, fields (each: signerId, fieldType, then either pageNumber/xPosition/yPosition/width/height or anchorText/occurrence?/position?, plus the field properties) | Prepare documents |
fill_fields | Writes the answers into the fields, so the person is left with the signature: text, dates in the field’s format, checkboxes ("true"/"false"), dropdowns, and checkboxes or radio options (ticking one member of a choose-one group clears the others). Works while the document is a draft and while it is out for signature, so an answer can still be corrected, but not once the signer it belongs to has signed. A signature or initials field is refused: the person draws it. Each value is validated exactly as the signer’s own typing is, and judged on its own, so one refusal does not cost the rest. The answer lists what is still unfilled and names anything that would still block signing. | documentId, values (each: fieldId, value) | Prepare documents |
prepare_for_signature | The one-call form for the simple case: one signer, one free place to sign, no signature field yet. It places that one. For anything else it places nothing and hands back the places it found and the signers still waiting, for the assistant to pair with add_fields. It will not pair them itself: the order blanks appear on a page has nothing to do with the order signers were added, and nothing printed on the page says whose a line is. | documentId | Prepare documents. Also needs View documents and templates |
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.
Field properties
Six field types: signature, initials, date, text, checkbox and
dropdown. A dropdown needs its options; without them the API refuses it,
because it would be a text box that only looks like a list.
add_field, add_field_at_text, update_field and the template field tools
all take the same properties, so a field built by an assistant is the same
field a person builds in Korala.
| Property | What it does |
|---|---|
label | What the signer sees on the field. |
required | Whether signing is blocked until it is filled. |
options | The choices a dropdown offers, in order. |
editable | For a field you prefill: whether the signer may change the value. |
sharedFill | One signer owns the field; until they sign, any signer able to act may fill or correct it. Refused on signature and initials fields. |
signingDate | Date fields only: true fills the field with the date of signing, so the signer does not type it; false makes it a date they enter. |
maxLength | Longest value a text field accepts. |
multiline | A text field that takes more than one line. |
inputMask | A fill pattern such as ###-##-####. Each # takes one digit; Korala types the rest in. |
validationPattern, validationMessage | A regular expression the value must match, and what the signer is told when it does not. |
dateFormat | How a date renders, e.g. MM/DD/YYYY. |
fontSize, fontFamily, textAlign, textColor | How the value is drawn. Omit fontSize to fit the size to the box. |
groupKey, groupRequired | Ties checkboxes into one choice among several, and requires one of them. |
requiredWhenFieldId, requiredWhenValue | Makes this field required only while another field holds a given value. |
acroFieldName, acroOptionValue | Links the field to a fillable PDF’s own form field, from get_form_fields, so the value is written through the form rather than drawn over it. |
On update_field and update_template_field, acroFieldName,
acroOptionValue, inputMask, requiredWhenFieldId and requiredWhenValue
also take null, which clears them.
Template fields add mergeFieldName, the name of the value that fills the
field when a document is created from the template, and defaultValue.
Coordinates
Most placements need none: import_form_fields and add_field_at_text work from the PDF’s own form and text. add_field is for the rest, and an agent that can render the PDF may place by eye. It needs three facts.
- Origin and direction. The origin is the top-left corner of the page.
xgrows to the right andygrows down, exactly like pixels in an image. PDF’s own coordinate system starts at the bottom-left withygrowing up; Korala does not use it, so an agent must never flipy. - Units. PDF points, 72 to the inch. US Letter is 612 × 792 and A4 is 595 × 842.
find_textreturns the real size of every page. - What a position means.
xPositionandyPositionare the top-left corner of the field;widthandheightextend right and down from it.
An agent that holds the file should render it itself: that needs nothing from Korala but the rules above and the page size. Render the page by itself, for example pdftoppm -r 72 -png, where one pixel is one point. At another resolution multiply every pixel value by page points ÷ image pixels. A 1275-pixel-wide render of a 612-point page scales by 0.48, so a box at pixel (250, 1500) sized 375 × 83 becomes xPosition 120, yPosition 720, width 180, height 40.
An agent that cannot render the file, such as a chat assistant, calls view_page: it returns the page with rulers already in these units and outlines the placed fields, so it also serves to check a placement. Korala renders a page once and keeps the picture until the fields on that page change.
Do not measure a screenshot of a PDF viewer: its margins, toolbar and zoom make pixel positions meaningless. Do not place from an image on a rotated page, which find_text marks.
create_upload_url serves coding agents that hold the file and can make HTTP requests. A chat assistant uses upload_attached_pdf when the chat app hands it the attachment, and request_pdf_upload otherwise. See Working with a PDF you already have.
Korala marks send_document, void_document, remove_signer, remove_field and remove_template_field as destructive: they email people or cannot be undone. Assistants that honor the mark, such as ChatGPT, ask you to confirm before they call them.
Worked example
You are connected with Send and void documents off.
You: I need an NDA for Anna Miller, [email protected]. My company is Acme Inc.
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], James Carter. 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 Miller”. 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.