Kema Invoice

Import external invoice

import_external_invoice

Import a historical/external invoice with its OWN invoice number (kept verbatim), totals, and status - no line items. Use for migrating past invoices issued outside Kema Invoice; NOT for creating new invoices (use create_invoice).

Input Schema

TableJSON Schema

Name	Required	Description
`notes`	No	Free text kept with the imported record (max 2000 characters).
`status`	Yes	Status of the historical invoice as it stands today.
`currency`	No	ISO 4217 currency code. Defaults to EUR.
`due_date`	No	Due date, YYYY-MM-DD. Defaults to issue_date + 30 days.
`company_id`	No	Client company UUID (use list_companies to resolve); null or omitted when unknown.
`issue_date`	Yes	Original issue date, YYYY-MM-DD.
`net_amount`	Yes	Total excl. VAT.
`tax_amount`	No	VAT amount. Defaults to 0.
`gross_amount`	No	Total incl. VAT. Defaults to net + tax.
`invoice_number`	Yes	The external number, kept as-is.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	Invoice UUID.
`type`	Yes	Document type: invoice, credit_note, provision or quote.
`notes`	Yes	Notes printed on the document.
`status`	Yes	Document status: Draft, Sent, Paid, Overdue, Cancelled, Rectified, Accepted, Rejected or Expired.
`paid_at`	Yes	Payment timestamp (ISO 8601), null while unpaid.
`sent_at`	Yes	Issue timestamp (ISO 8601), null while Draft.
`currency`	Yes	ISO 4217 currency code (EUR, USD, GBP or CHF).
`due_date`	Yes	Due date, YYYY-MM-DD.
`matter_id`	Yes	Matter (dossier) UUID, null when unassigned.
`net_total`	Yes	Total excl. VAT, in the document currency.
`tax_total`	Yes	VAT amount, in the document currency.
`amount_due`	Yes	Gross total minus applied provisions, null when not computed.
`company_id`	Yes	Client company UUID.
`created_at`	Yes	Creation timestamp (ISO 8601).
`issue_date`	Yes	Issue date, YYYY-MM-DD.
`updated_at`	Yes	Last update timestamp (ISO 8601).
`gross_total`	Yes	Total incl. VAT, in the document currency.
`valid_until`	Yes	Quote validity limit, YYYY-MM-DD; null for other types.
`vat_scenario`	Yes	Fiscal scenario frozen at creation (e.g. domestic, eu_b2b_reverse_charge).
`payment_terms`	Yes	Payment terms: Net-15, Net-30, Net-60, Net-90 or Due on Receipt.
`advances_total`	Yes	Sum of provisions applied, in the document currency.
`created_source`	Yes	Origin of the document: manual (app) or mcp (agent).
`credit_note_id`	Yes	Credit note UUID that cancelled this invoice.
`internal_notes`	Yes	Private notes, never printed.
`invoice_number`	Yes	Human-readable document number.
`invopop_status`	Yes	Fiscal certification status from the provider, null before issuance.
`source_quote_id`	Yes	Quote UUID this invoice was converted from.
`delivery_channel`	Yes	Delivery channel: Email, e-Invoice or Manual.
`replaces_invoice_id`	Yes	Original invoice UUID when this is a rectificative.
`replaced_by_invoice_id`	Yes	Rectificative UUID when this invoice was rectified.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedSep 7, 2026

addedInput schema / properties / company_id / description

Added value: +"Client company UUID (use list_companies to resolve); null or omitted when unknown."

addedInput schema / properties / currency / description

Added value: +"ISO 4217 currency code. Defaults to EUR."

changedInput schema / properties / due_date / description

Previous value: -"Defaults to issue_date + 30 days."New value: +"Due date, YYYY-MM-DD. Defaults to issue_date + 30 days."

changedInput schema / properties / gross_amount / description

Previous value: -"Defaults to net + tax."New value: +"Total incl. VAT. Defaults to net + tax."

addedInput schema / properties / issue_date / description
```
Added value: +"Original issue date, YYYY-MM-DD."
```

addedInput schema / properties / notes / description

Added value: +"Free text kept with the imported record (max 2000 characters)."

addedInput schema / properties / status / description

Added value: +"Status of the historical invoice as it stands today."

addedInput schema / properties / tax_amount / description
```
Added value: +"VAT amount. Defaults to 0."
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "advances_total": {
+      "description": "Sum of provisions applied, in the document currency.",
+      "type": "number"
+    },
+    "amount_due": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Gross total minus applied provisions, null when not computed."
+    },
+    "company_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Client company UUID."
+    },
+    "created_at": {
+      "description": "Creation timestamp (ISO 8601).",
+      "type": "string"
+    },
+    "created_source": {
+      "description": "Origin of the document: manual (app) or mcp (agent).",
+      "type": "string"
+    },
+    "credit_note_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Credit note UUID that cancelled this invoice."
+    },
+    "currency": {
+      "description": "ISO 4217 currency code (EUR, USD, GBP or CHF).",
+      "type": "string"
+    },
+    "delivery_channel": {
+      "description": "Delivery channel: Email, e-Invoice or Manual.",
+      "type": "string"
+    },
+    "due_date": {
+      "description": "Due date, YYYY-MM-DD.",
+      "type": "string"
+    },
+    "gross_total": {
+      "description": "Total incl. VAT, in the document currency.",
+      "type": "number"
+    },
+    "id": {
+      "description": "Invoice UUID.",
+      "type": "string"
+    },
+    "internal_notes": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Private notes, never printed."
+    },
+    "invoice_number": {
+      "description": "Human-readable document number.",
+      "type": "string"
+    },
+    "invopop_status": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Fiscal certification status from the provider, null before issuance."
+    },
+    "issue_date": {
+      "description": "Issue date, YYYY-MM-DD.",
+      "type": "string"
+    },
+    "matter_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Matter (dossier) UUID, null when unassigned."
+    },
+    "net_total": {
+      "description": "Total excl. VAT, in the document currency.",
+      "type": "number"
+    },
+    "notes": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Notes printed on the document."
+    },
+    "paid_at": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Payment timestamp (ISO 8601), null while unpaid."
+    },
+    "payment_terms": {
+      "description": "Payment terms: Net-15, Net-30, Net-60, Net-90 or Due on Receipt.",
+      "type": "string"
+    },
+    "replaced_by_invoice_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Rectificative UUID when this invoice was rectified."
+    },
+    "replaces_invoice_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Original invoice UUID when this is a rectificative."
+    },
+    "sent_at": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Issue timestamp (ISO 8601), null while Draft."
+    },
+    "source_quote_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Quote UUID this invoice was converted from."
+    },
+    "status": {
+      "description": "Document status: Draft, Sent, Paid, Overdue, Cancelled, Rectified, Accepted, Rejected or Expired.",
+      "type": "string"
+    },
+    "tax_total": {
+      "description": "VAT amount, in the document currency.",
+      "type": "number"
+    },
+    "type": {
+      "description": "Document type: invoice, credit_note, provision or quote.",
+      "type": "string"
+    },
+    "updated_at": {
+      "description": "Last update timestamp (ISO 8601).",
+      "type": "string"
+    },
+    "valid_until": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Quote validity limit, YYYY-MM-DD; null for other types."
+    },
+    "vat_scenario": {
+      "description": "Fiscal scenario frozen at creation (e.g. domestic, eu_b2b_reverse_charge).",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "invoice_number",
+    "type",
+    "status",
+    "company_id",
+    "matter_id",
+    "issue_date",
+    "due_date",
+    "valid_until",
+    "currency",
+    "payment_terms",
+    "delivery_channel",
+    "net_total",
+    "tax_total",
+    "gross_total",
+    "advances_total",
+    "amount_due",
+    "notes",
+    "internal_notes",
+    "paid_at",
+    "sent_at",
+    "invopop_status",
+    "vat_scenario",
+    "source_quote_id",
+    "replaces_invoice_id",
+    "replaced_by_invoice_id",
+    "credit_note_id",
+    "created_source",
+    "created_at",
+    "updated_at"
+  ],
+  "type": "object"
+}

First observedSep 7, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations indicate this is not read-only and not destructive. The description adds useful context about preserving the invoice number and excluding line items, though it does not detail write-specific side effects beyond the import intent.

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?

The description is two sentences, front-loads the core purpose, and immediately communicates key exclusions and the alternative tool. No unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the parameter schema fully documents each field and the description clarifies the migration use case and boundary with create_invoice, the tool is well contextualized. An output schema exists, so return-value details are not required.

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?

All 10 parameters are described in the schema with defaults, enums, and helpful hints such as 'use list_companies to resolve'. The tool description reinforces the overall purpose but adds little beyond the already high schema coverage.

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 description states a specific verb ('Import'), a clear resource ('historical/external invoice'), and distinguishes it from create_invoice. It also clarifies the preservation of the external invoice number and the absence of line items.

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?

Explicitly states when to use the tool ('for migrating past invoices issued outside Kema Invoice') and when not to use it ('NOT for creating new invoices'), including the alternative tool name.

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

All Kema Invoice 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.