Carbone MCP

Official

Overview Schema Source Related Servers Discussions Admin

Upload Template

upload_template

Upload and store a reusable Carbone template. Once uploaded, use render_document with the returned Template ID to generate documents from it.

Instructions

Upload and store a reusable Carbone template. Once uploaded, use render_document with the returned Template ID to generate documents from it. Supports versioning: multiple versions can live under a single stable Template ID, and rendering by Template ID uses the version with the most recent deployedAt. A result deployedAt of 0 means the version is not explicitly deployed: if another version of the same Template ID is deployed, renders by Template ID keep using that one. Accepted formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, Markdown, TXT, CSV, RTF and PDF (not the legacy binary DOC, XLS or PPT).

Input Schema

TableJSON Schema

Name	Required	Description
`id`	No	Existing Template ID (64-bit format) to add this upload to its version history. If omitted, a new Template ID is generated. Providing a Version ID (SHA-256) is not allowed and will cause an error.
`name`	No	Display name for the template, max 200 characters (e.g. "Invoice Template", "NDA Contract"). Optional but recommended: list_templates shows it and its search matches it.
`tags`	No	Labels shown by list_tags and on each list_templates result (e.g. ["sales", "billing", "v2"]). Duplicates are removed and the list is sorted; the whole list is limited to 100 characters (about 8 tags of 9 characters).
`sample`	No	Sample input data attached to the template for testing in Carbone Studio: an array with at most ONE object, whose keys data, complement, translations and enum are all optional. Example: [{ "data": { "name": "Acme" } }].
`comment`	No	Free-text comment to describe the template version or its purpose, max 200 characters.
`category`	No	Group templates into folders/categories, max 200 characters (e.g. "invoices", "legal", "hr").
`expireAt`	No	Schedule deletion at a UTC Unix timestamp (seconds); 0 (default) means the template never expires. After that time it is no longer listed, downloadable or renderable (404), and the file is purged after the retention delay. To remove a template now, use delete_template.
`template`	Yes	The template file. Three input forms are accepted: (1) Local file path — absolute, e.g. "/Users/me/report.docx" (or "C:\Users\me\report.docx" on Windows), or under the home directory, e.g. "~/report.docx". A relative path must start with "./" or "../" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as "report.docx" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first.
`deployedAt`	No	UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special "NOW" sentinel value). Future values are not allowed.
`versioning`	No	Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash) and templateExtension.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	No	Stable Template ID (when versioning is enabled).
`name`	No	Template display name, when one was given.
`size`	No	Template size in bytes.
`type`	No	Detected template file type.
`createdAt`	No	UTC Unix timestamp (seconds) of the upload.
`versionId`	No	Version ID (SHA-256) of this uploaded version.
`deployedAt`	No	UTC Unix timestamp of deployment; 0 means this version is not explicitly deployed.
`templateId`	No	Template ID returned in legacy/non-versioned mode.
`templateExtension`	No	Detected file extension, e.g. "docx" (legacy/non-versioned mode).

Schema Changelog

Changes observed during successful MCP inspections.

Changed24 schema fields changedv2.0.0Oct 14, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / category / description

Previous value: -"Group templates into folders/categories (e.g. \"invoices\", \"legal\", \"hr\")."New value: +"Group templates into folders/categories, max 200 characters (e.g. \"invoices\", \"legal\", \"hr\")."

addedInput schema / properties / category / maxLength
```
Added value: +200
```

changedInput schema / properties / comment / description

Previous value: -"Free-text comment to describe the template version or its purpose."New value: +"Free-text comment to describe the template version or its purpose, max 200 characters."

addedInput schema / properties / comment / maxLength
```
Added value: +200
```

changedInput schema / properties / deployedAt / description

Previous value: -"UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special \"NOW\" sentinel value)."New value: +"UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special \"NOW\" sentinel value). Future values are not allowed."

changedInput schema / properties / expireAt / description

Previous value: -"UTC Unix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately (special \"NOW\" sentinel value)."New value: +"Schedule deletion at a UTC Unix timestamp (seconds); 0 (default) means the template never expires. After that time it is no longer listed, downloadable or renderable (404), and the file is purged after the retention delay. To remove a template now, use delete_template."

changedInput schema / properties / expireAt / minimum
```
Previous value: --9007199254740991New value: +0
```

changedInput schema / properties / name / description

Previous value: -"Display name for the template (e.g. \"Invoice Template\", \"NDA Contract\")."New value: +"Display name for the template, max 200 characters (e.g. \"Invoice Template\", \"NDA Contract\"). Optional but recommended: list_templates shows it and its search matches it."

addedInput schema / properties / name / maxLength
```
Added value: +200
```

changedInput schema / properties / sample / description

Previous value: -"Sample input data attached to the template for testing in Carbone Studio. Each item must include data, complement, translations, and enum objects."New value: +"Sample input data attached to the template for testing in Carbone Studio: an array with at most ONE object, whose keys data, complement, translations and enum are all optional. Example: [{ \"data\": { \"name\": \"Acme\" } }]."

addedInput schema / properties / sample / items / additionalProperties
```
Added value: +false
```

removedInput schema / properties / sample / items / required

Removed value: -[
-  "data",
-  "complement",
-  "translations",
-  "enum"
-]

addedInput schema / properties / sample / maxItems
```
Added value: +1
```

changedInput schema / properties / tags / description

Previous value: -"Tags for searchability and filtering (e.g. [\"sales\", \"billing\", \"v2\"])."New value: +"Labels shown by list_tags and on each list_templates result (e.g. [\"sales\", \"billing\", \"v2\"]). Duplicates are removed and the list is sorted; the whole list is limited to 100 characters (about 8 tags of 9 characters)."

changedInput schema / properties / template / description

Previous value: -"The template file. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"New value: +"The template file. Three input forms are accepted: (1) Local file path — absolute, e.g. \"/Users/me/report.docx\" (or \"C:\\Users\\me\\report.docx\" on Windows), or under the home directory, e.g. \"~/report.docx\". A relative path must start with \"./\" or \"../\" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as \"report.docx\" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first."

changedInput schema / properties / versioning / description

Previous value: -"Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash)."New value: +"Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash) and templateExtension."

changedInput schema / required

Previous value: -[
-  "template",
-  "name"
-]New value: +[
+  "template"
+]

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / properties / createdAt

Added value: +{
+  "description": "UTC Unix timestamp (seconds) of the upload.",
+  "type": "number"
+}

addedOutput schema / properties / deployedAt

Added value: +{
+  "description": "UTC Unix timestamp of deployment; 0 means this version is not explicitly deployed.",
+  "type": "number"
+}

changedOutput schema / properties / name / description

Previous value: -"Template display name."New value: +"Template display name, when one was given."

addedOutput schema / properties / templateExtension

Added value: +{
+  "description": "Detected file extension, e.g. \"docx\" (legacy/non-versioned mode).",
+  "type": "string"
+}

removedOutput schema / required
```
Removed value: -[
-  "name"
-]
```

Changed1 schema field changedv1.6.0Aug 22, 2026

changedInput schema / properties / template / description

Previous value: -"The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"New value: +"The template file. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"

Changed2 schema fields changedv1.2.2Jun 25, 2026

changedInput schema / properties / template / description

Previous value: -"The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type"New value: +"The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "description": "Stable Template ID (when versioning is enabled).",
+      "type": "string"
+    },
+    "name": {
+      "description": "Template display name.",
+      "type": "string"
+    },
+    "size": {
+      "description": "Template size in bytes.",
+      "type": "number"
+    },
+    "templateId": {
+      "description": "Template ID returned in legacy/non-versioned mode.",
+      "type": "string"
+    },
+    "type": {
+      "description": "Detected template file type.",
+      "type": "string"
+    },
+    "versionId": {
+      "description": "Version ID (SHA-256) of this uploaded version.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "type": "object"
+}

First observedv1.1.2May 8, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the write/new-resource profile is covered. The description does add genuinely useful behavior beyond that: the versioning model (multiple versions under one stable Template ID, most-recent deployedAt wins) and the deployedAt=0 non-deployment case. That is real added value, but it stops short of stating auth requirements, size limits or what happens to an existing version on re-upload.

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

Conciseness4/5

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

Front-loaded with purpose, then downstream usage, then versioning, then formats — good ordering with no filler prose. It loses a point because the trailing enumeration of accepted formats largely restates the template parameter's own schema description.

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?

For a 10-parameter, output-schema-backed tool, the description covers the ambiguous parts an agent would otherwise guess at: versioning identity, deployedAt precedence and format acceptance/rejection. Return-value detail is correctly left to the output schema.

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 per-parameter baseline is 3. The description still earns above baseline by explaining the version-selection rule that governs how id and deployedAt interact at render time — semantics that live outside the individual parameter docs.

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?

"Upload and store a reusable Carbone template" names a specific verb and resource, and the definition goes further by naming the downstream consumer (render_document) and the return value (Template ID). An agent can distinguish it from siblings like convert_document, update_template_metadata or render_document without opening any schema.

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?

It clearly states the post-upload path ("use render_document with the returned Template ID") and, via the expireAt parameter text, points to delete_template for immediate removal. However it never states when NOT to upload, e.g. that metadata-only changes belong to update_template_metadata or that convert_document is the route for changing format.

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

Deploy Server

Upload Template

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools